> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Project Knowledge
> Structured project context in the Project Knowledge drawer — shared between agents and available for you to shape
export const ProductName = "The Morph Platform";
export const productName = "the Morph Platform";
**Project Knowledge** is where all structured project context lives in the product — the Project Spec, **Project Setup** (lifecycle scripts, environment variables, dependencies, Dockerfile), milestones, wikis, and rules — together with **Knowledge chat** for conversing with {productName}. You open it from the **Roadmap**: under **Modernization**, click **Project Knowledge**. The first time your project starts, {productName} opens this drawer for you so you can **go through onboarding** — discovering and validating the application's lifecycle alongside the agent — and later **review and approve the Project Spec**. Throughout the migration, agents read from and write to the same underlying knowledge; this UI is how you inspect and steer it.
Older documentation called this drawer the "Knowledge Hub." That name is retired — the UI label is **Project Knowledge**.
## What Project Knowledge Is
Think of Project Knowledge as **structured context for Morph agents**, surfaced in a full-height drawer on the Roadmap. Every time an agent works on a task, it reads this knowledge to understand your project's architecture, conventions, how the application actually runs, and decisions already made. When an agent learns something new during execution — a pattern it discovered, an architectural decision, a fix to a startup script — it writes that back (often as wiki pages or as updates to the lifecycle setup).
This is how agents pass knowledge to each other. Onboarding establishes how the app installs, builds, and runs. Milestone 1 might establish a database access pattern. Milestone 5, handled by a different agent, reads both of those from the same project knowledge and follows them. The result is consistent code across your migration — and a configuration the agent can actually run — even when different agents handle different parts.
### What's Inside
Project Knowledge is organized in a tree with five kinds of content:
| Type | What It Holds | How It's Used |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Project Spec** | Goals, scope, and approach for the migration | Agents reference the Project Spec to stay aligned with the overall direction |
| **Project Setup** | Lifecycle scripts (install / build / run / healthcheck / test), environment variables and secrets, the lifecycle document, dependencies, and the Dockerfile — for both the **origin** and **target** sides | Agents use the lifecycle to actually run, validate, and functionally test the application at every step |
| **Milestones** | Detailed descriptions and scope for each migration step | Agents use milestone content to understand what each step requires |
| **Wiki** | Architecture docs, design decisions, patterns discovered during migration | Agents read wikis to understand project context and conventions |
| **Rules** | Coding standards, library preferences, explicit constraints | Agents follow rules as hard requirements in every milestone |
### How Agents Use It
When an agent starts working on a milestone:
1. It reads the **Project Spec** to understand the migration's overall goals
2. It reads the **Project Setup** to know how to install, build, run, and health-check the app
3. It reads all **rules** to know which standards to follow
4. It reads relevant **wiki pages** to understand architecture and patterns
5. It reads the **milestone description** to know what to build
After execution, the agent writes back anything it learned — new patterns, architectural decisions, integration notes, and any lifecycle fixes it needed to make the app run — as wiki pages or as updates to the lifecycle configuration. That keeps project knowledge growing and more accurate over the course of the migration.
## Opening Project Knowledge
**First time (onboarding):** When you create a new project, the **Project Setup** stage on the Roadmap opens this drawer for you with **Knowledge chat** seeded to start onboarding — the agent walks you through discovering and validating how your application installs, builds, runs, and is health-checked. See [Project Setup (Onboarding)](#project-setup-onboarding) below.
**After onboarding:** When your Project Spec finishes generating, the drawer opens again (usually with **Project Spec** selected) so you can review and approve it.
**Any time after that:** Go to the project's **Roadmap**. In the left **Modernization** column, click **Project Knowledge** to open the drawer. You can also open it from flows that link knowledge (for example, opening a rule, milestone, or lifecycle script in context).
## Project Setup (Onboarding)
**Project Setup** is the branch of the Project Knowledge tree that holds everything {productName} needs to actually *run* your application. It's also **where onboarding happens at the beginning of every project** — the first time you open the drawer, the agent collaborates with you in **Knowledge chat** to fill this branch in.
The branch is organized by side of the migration, mirroring the rest of project knowledge:
* **Origin** — How the source application builds and runs. Discovered together with you during onboarding and used as the behavioral baseline for [functional testing](/migration/functional-testing).
* **Target** — How the destination application builds and runs. Discovered automatically during the foundation milestone (Milestone 1) so the target side is ready before migration code starts landing.
* **Dependencies** and **Dockerfile** — Project-wide artifacts the agent builds during onboarding and keeps in sync as the project evolves.
Each origin/target entry contains three sub-items you can select in the tree:
| Sub-item | What it is |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Scripts** | Ordered shell scripts — typically `install`, `build`, `run`, `healthcheck`, and `test` — that bring the app to a healthy, running state |
| **Environment Variables** | Variables and secrets the app needs at build or runtime, discovered from the codebase or set explicitly. Secrets are encrypted at rest |
| **Lifecycle Document** | A markdown overview describing the application's architecture, the execution order of scripts, and how each phase fits together |
### How onboarding flows through this drawer
When you start a new project, the **Project Setup** stage on the Roadmap routes you into the Project Knowledge drawer with the chat focused on lifecycle discovery. From there:
1. The agent inventories your repository — framework, install/build/run commands, healthcheck signals, env vars and secrets, external service dependencies — and **reports back what it found** before writing anything.
2. It proposes the lifecycle **phases** (install / build / run / healthcheck / test, plus optional steps like `migrate` or per-service splits in multi-environment projects) and confirms them with you.
3. It registers the **scripts** and **environment variables**, asking you for any values it can't infer (API keys, service URLs, tenant-specific config).
4. It **executes the lifecycle end-to-end** to validate it actually works. On failure, it surfaces the failing phase, the last lines of output, and a proposed fix before retrying.
5. Once validation passes, the lifecycle is marked **Validated** and onboarding hands off to Project Spec generation. If the agent can't get it fully healthy, the configuration is saved as **Draft — Needs Review** for you to correct manually.
You can see all of this happen live in the drawer: the tree on the left shows the Project Setup branch filling in as the agent works, and the chat on the right is where you answer questions and approve choices.
### Editing the lifecycle later
Lifecycle artifacts are read-only when selected directly in the tree — to change them, ask **Knowledge chat** and the agent will update them for you. Typical asks:
```
The run script should bind to port 8080, not 3000.
Re-validate after the change.
```
```
Add a `migrate` script that runs `alembic upgrade head` before `run`.
```
```
DATABASE_URL should point at a local Postgres on localhost:5432
for validation. Save it as a regular env var, not a secret.
```
For a deeper reference on the lifecycle data model, validation states, and the standalone Lifecycle Setup page, see [Lifecycle Setup](/setup/build-environment/lifecycle-setup).
## Adding Your Own Knowledge
You can add context at any time. This is useful when you have documentation, design decisions, or standards that {productName} should know about from the start.
When you add content, it isn't stored as a single blob. {productName} breaks it down into structured **wiki pages** and **rules**, optimized for how agents consume it. A long design doc becomes focused, referenceable entries agents can query efficiently.
### Using the Chat
Use the **Knowledge chat** panel to talk to {productName} and create, update, or reorganize knowledge.
**To add documentation:**
1. Open **Project Knowledge** from the Roadmap (**Modernization** → **Project Knowledge**)
2. Open the chat panel if it is hidden
3. Describe what you want to add
For example:
```
We use the repository pattern for all database access.
Each entity has its own repository class that extends BaseRepository.
Repositories handle all SQL queries — services never write raw SQL.
Here's an example from our codebase:
class UserRepository(BaseRepository[User]):
async def find_by_email(self, email: str) -> User | None:
return await self.find_one({"email": email})
```
{productName} takes this and creates the appropriate wiki pages and rules so that every agent follows this pattern.
### Dragging in Files
You can drag text files directly onto the chat panel to import existing documentation. {productName} reads the file, extracts the relevant knowledge, and creates wiki pages and rules from it.
Supported formats include `.md`, `.txt`, `.yaml`, `.json`, `.py`, `.ts`, `.js`, and many more text-based files.
**Example use cases:**
* Drag your team's `CONTRIBUTING.md` to import coding standards
* Drop an architecture decision record (ADR) to capture design choices
* Import a `styleguide.md` to encode formatting preferences
### From a URL or Repo Path
In the chat, you can also reference external sources:
```
Please read the coding standards from our wiki at
https://internal-wiki.example.com/coding-standards
and create rules from them.
```
Or point to a file in your repository:
```
Read the patterns in src/shared/base-repository.ts
and create a wiki page documenting the repository pattern we use.
```
## Editing Wiki Pages
Wiki pages capture architecture, patterns, and project-specific context. Update them through the chat.
Right-click a wiki page in the tree and select **Add to Context** to attach it to the chat. Then describe the change you want:
```
Add a section about connection pooling.
We use a max of 20 connections per service instance.
```
```
Create a new wiki page about our error handling strategy.
All domain errors should extend AppError. HTTP errors are mapped
in the error middleware, not in individual handlers.
```
### When to Add Wiki Pages
Add wiki pages when you have knowledge that applies broadly but isn't a hard rule:
* **Architecture decisions** — "We chose event sourcing for the order service because..."
* **Integration notes** — "The payment gateway expects ISO 8601 dates with timezone"
* **Migration context** — "The legacy `UserManager` class maps to three separate services in the new architecture"
* **Patterns** — "All API responses follow the envelope pattern: `{ data, meta, errors }`"
## Editing Rules
Rules are hard constraints that agents follow in every milestone. Unlike wiki pages (which provide context), rules are treated as requirements. Create and update rules through the chat:
```
Create a rule: all Python files must use absolute imports.
No relative imports allowed except in __init__.py files.
```
To update an existing rule, right-click it in the tree and select **Add to Context**, then describe the change:
```
Update this rule to also require that every new endpoint
has at least one integration test.
```
### Rules vs. Wiki Pages
| | Rules | Wiki Pages |
| ------------------ | ------------------------------------------------------ | --------------------------------------------------------- |
| **Agent behavior** | Treated as requirements — agents must follow them | Treated as context — agents use them to inform decisions |
| **Scope** | Apply to every milestone | Referenced when relevant |
| **Best for** | Coding standards, library mandates, naming conventions | Architecture docs, design decisions, integration notes |
| **Example** | "Use pytest for all tests. No unittest." | "The authentication service uses JWT with RS256 signing." |
Use rules when you want to **enforce** something. Use wiki pages when you want to **inform** agents.
## Editing Milestones
You can review milestone descriptions in Project Knowledge. To adjust scope, add requirements, or change descriptions, use [Editing Milestones](/customization/editing-milestones) from the milestone review flow.
You can also ask {productName} to restructure milestones through chat. For example, to merge two milestones:
```
Merge Milestone 3 ("Migrate user authentication") and
Milestone 4 ("Migrate session management") into a single milestone.
They're tightly coupled and should be done together.
```
### Locked Milestones
Milestones that are in progress, under review, or already merged cannot be edited. Only milestones with a **Not Started** status are editable.
If you need to adjust a milestone that's already executing, wait for the current execution to complete and then make your changes before re-running.
For small, recurring adjustments across milestones, add a [Rule](#editing-rules) instead of editing each milestone individually. Rules apply to all milestones automatically.
## Updating the Project Spec
The **Project Spec** is the top-level document that defines your migration's goals, scope, and approach. Ask {productName} in chat to refine the migration direction; substantial changes may also go through your Project Spec approval flow (see [Reviewing the Project Spec](/setup/reviewing-project-spec)).
Changes to the Project Spec can affect how agents approach future milestones, so be deliberate about what you request.
## Viewing Changes
When {productName} modifies knowledge during an agent execution (for example, an agent discovers a pattern and writes a wiki page), you can see exactly what changed.
Click **Highlight changes** (the diff icon) in the Project Knowledge toolbar to toggle an inline diff view:
* **Green** highlights show added content
* **Red** highlights with strikethrough show removed content
* A summary shows the total lines added and removed
* Modified items are marked with a yellow indicator in the tree navigation
This makes it easy to review what agents learned and wrote back during execution.
## How Knowledge Stays in Sync
Project knowledge stays aligned with running work as agents read and write it, and as you add or update context through the chat. When you ask for changes while an agent is running, {productName} incorporates them so agents can pick up new rules and wiki context in subsequent steps.
## Examples
### Setting Up a New Project's Knowledge
When you start a migration, front-load project knowledge with what you know:
```
Our project follows clean architecture. The layers are:
- Domain (entities, value objects, repository interfaces)
- Application (use cases, DTOs, application services)
- Infrastructure (database repos, external API clients, message handlers)
- Presentation (controllers, middleware, request/response models)
Dependencies point inward. Infrastructure depends on Domain,
never the reverse. Use dependency injection everywhere.
```
{productName} creates wiki pages for the architecture and rules for the dependency direction constraint.
### Correcting Agent Behavior
After reviewing a PR, you notice agents are using `console.log` for debugging:
```
Create a rule: never use console.log in production code.
Use the logger service from src/shared/logger.ts for all logging.
Debug logs should use logger.debug(), errors should use logger.error()
with the full error object.
```
All future milestones follow this rule.
### Importing Team Standards
Your team has a `docs/coding-standards.md` in the repo:
1. Drag the file onto the Knowledge chat panel
2. {productName} reads it and says: *"I've extracted 4 rules and 2 wiki pages from your coding standards document..."*
3. Review the created entries in the tree navigation
4. Ask the chat to adjust any entries that need refinement
### Adding Context Mid-Migration
At Milestone 4, you realize agents don't know about a critical integration:
```
The user service calls the billing service over gRPC.
The proto files are in shared/proto/billing.proto.
When migrating user-related code, preserve all billing
service calls and use the generated Python client from
shared/generated/billing_pb2_grpc.py.
```
Milestones 5 onwards now have this context.
## Best Practices
### Let the Chat Do the Structuring
Don't worry about formatting your input perfectly. Describe what you want in natural language and {productName} structures it into the right wiki pages and rules. A rough paragraph of context works better than trying to manually create the "right" wiki page.
### Review Agent-Created Knowledge
After each milestone, open Project Knowledge and check for new wiki entries. Agents write back what they learned. If something is inaccurate, ask the chat to correct or remove it before the next milestone picks it up.
### Use Rules for Enforcement, Wikis for Context
If you find yourself writing a wiki page that says "always do X" — that's a rule. Move it there so agents treat it as a hard requirement, not optional context.
***
## Related Docs
Reference for lifecycle scripts, env vars, validation status, and re-validation
Approve the Project Spec using Project Knowledge and chat
Deep dive into writing effective rules with examples
How to adjust milestone scope and descriptions
Morph terminology and mental model