# Set up knowledge for a repo

Let EasyCode scan a repo and map your org's code, so every session can read how the repos fit together before it changes anything.

A session that only sees one folder misses how the org's repos fit together: which service publishes an event, who
calls a route, where an env key is read. Knowledge gives every session in your org the whole picture. It works from
the code itself, on your team's own machines and GitHub logins.

> **A module**
>
> Knowledge is a module. With it off, a product's **Knowledge** tab says "Knowledge is off for" your org, and only
> **Overview** shows until an admin turns it on.

## What it does

There are three parts, and the first two need nothing from you once a repo is in a product.

- **The scan.** The desktop app reads each repo of your org's products and builds an index of its code facts:
  routes, client calls, events published and handled, queues, packages, scripts, env keys and symbols. Only names,
  paths, line numbers and one-line signatures go to EasyCode, never code bodies, and secret-shaped values are dropped.
  The scan reads the default branch from git. It never reads your working folder, and nothing is installed, built or
  run.
- **The checkouts and the map.** In an org space, the app keeps a read-only checkout of each repo, at the head of its
  default branch. Beside them it writes the org map: `ORG.md`, one line per repo with its products, a summary and its
  key paths, and the `org/*.tsv` tables. Every row in a table ends in the `repo/path:line` it came from.
- **Model-written knowledge.** For each product, an admin can have a model propose its conventions and capture its
  design system. You review the result before it is published.

## Before you start

- The repo is linked to a product. On a product with none, the tab says "Link a repo in the product settings to set
  up its knowledge"; an admin or a maintainer does that. See [Products and repos](/setup/products-and-repos).
- The GitHub App can see the repo.
- Someone on the team runs the [desktop app](/setup/desktop-app) and can read the repo on GitHub.

## Let your computer scan

The scan runs on members' computers, through their own git login. In the desktop app, open **Settings**, then
**Desktop**, and turn on **Scan repos on this computer**: "When you can read a picked repo on GitHub, this computer reads
it and builds its index for the org." It's on by default ([`knowledge.scan`](/reference/settings#knowledge-scan)). A computer scans at
most three repos at a time, and a repo is scanned by one computer at a time.

When a scan fails for the repo's own sake, such as a refused clone, EasyCode records the error on the repo.

## What a session gets

When a session starts in an org space, its instructions carry a short "Org code" rule: every repo is checked out
read-only, and `ORG.md` maps the products and repos. Before changing files in a repo, the session reads that repo's
rows in the tables.

The map goes in whole while it fits. In a larger org the session gets its own product in full and one line for each
other repo, or one line per repo. The session's chip shows which: "Org map: full", "Org map: this product in full,
others one line" or "Org map: one line a repo". `ORG.md` itself always holds the whole map.

The tables are plain files a harness can grep:

| Table                                                     | What's in it                                                   |
| --------------------------------------------------------- | -------------------------------------------------------------- |
| `org/repos.tsv`                                           | Each repo, its indexed commit and default branch               |
| `org/products.tsv`                                        | Which repos make up each product, and their roles              |
| `org/routes.tsv`                                          | HTTP routes, by method                                         |
| `org/events.tsv`                                          | Events and topics, who publishes and who handles them          |
| `org/env.tsv`                                             | Where each env key is read                                     |
| `org/deps.tsv`                                            | Which repo depends on which, and how                           |
| `org/stack.tsv`, `org/components.tsv`, `org/commands.tsv` | The stack, the components and the commands each repo runs      |
| `org/agent-files.tsv`                                     | Each repo's own harness files, such as `CLAUDE.md`             |
| `org/owners.tsv`, `org/submodules.tsv`, `org/design.tsv`  | Code owners, submodules and design systems, when there are any |

The harness reads the checkouts and the map with its own file tools, under its own permissions. There is no separate
search tool to call.

## Propose conventions and capture the design system

On a product, open the **Knowledge** tab. "Repos are scanned on their own. These two are written by a model on the
assignee's computer, and you review the result before it is published."

### Start the task

Press **Propose conventions** (the product's rules and standards, each with its evidence in the code) or **Capture
the design system** (its tokens and components, read from its repos). Only admins and the product's maintainers start
these. Assign the task to a member who can see the product and read its repos on GitHub.

### Run it

The assignee opens the task and presses **Start run**. It runs in Claude Code or Codex on their machine, and shows to
the team as an org session titled with the task. **Retry** resumes a failed stage on the same machine.

### Review and publish

An approver opens the **Result for approval**, with its sections, evidence and provenance, and presses **Approve and
publish** or **Send back** with what to change. A published result becomes a library asset that sessions load.

To have your computer take tasks assigned to you on its own, turn on **Run my knowledge tasks in the background** in
the desktop app's **Desktop** settings ([`knowledge.autoRefresh`](/reference/settings#knowledge-autorefresh)). Org admins set the review rule and
the model per harness under **Settings**, **Knowledge**.

Your org admin can stop knowledge runs with the [`knowledge`](/reference/kill-switches-and-modules#knowledge) switch. Setup and review still work.

## Related

- [Start a session](/guides/start-a-session): what else a session gets
- [Bring your existing kit](/guides/bring-your-kit)
- [Design in every session](/design-system/in-every-session)
