---
url: /handbook/discovery/company-repo.md
description: The company as files an AI can read, with a state on every file.
---

# Company Repo

The **Company Repo** is the company as a tree of files: company and market, leadership, departments, roles, people, duties, Task Cards, flows, systems and authority. Each file has a state, so a reader can tell a researched fact from a confirmed one. People and AI tools read the same files.

Open **Repo** in the company sidebar.

## A view, not a second store

DutyGraph compiles the Repo from the records it already holds: research findings, confirmations, answers, Task Cards and the rest. You cannot type into a file. To change a file, change the data behind it, for example confirm a finding or accept an answer. The next compile shows the change. The same records always give the same files.

**DutyGraph Agent** beside the files answers questions and writes edit proposals. It only proposes. You accept or reject each one. See [DutyGraph Agent](../advisors/repo-copilot.md).

## The folders

Every company gets the same folders. Only the department and process files change with the company's shape.

| Folder | What it holds |
| --- | --- |
| `company/` | Profile, strategy, value chain, glossary, org chart and operating rhythm |
| `departments/` | One folder per department: charter, metrics, systems and risks. Derived from the team list. |
| `roles/` | One file per role: holders, duties, authority and systems |
| `people/` | Identity only: name, email and status. Each person's asks are in `people/<person>/asks/`. |
| `duties/` | Ongoing responsibilities. Each groups tasks and has one owner. |
| `tasks/` | Task Cards: steps, inputs, outputs, authority, and a runbook where one exists |
| `flows/` | Chains of tasks with their handoffs |
| `authority/` | Approval matrix, separation of duties, delegation and spend limits |
| `manifests/` | Draft agents and agent requests. Each waits for review. |
| `metrics/` | Measures with an owner, formula, baseline and target |
| `systems/` | Systems named by research, Task Cards and the engagement record |
| `policies/` | Rules the company must follow. Not compiled in this version. |
| `risks/` | Named risks. Not compiled in this version. |
| `findings/` | Possible constraints and the generated gaps list, `findings/gaps.md` |
| `market/` | Customers, competitors, market context, and dated events in `market/signals/` |
| `evidence/` | Evidence records and research runs: titles, types and dates only |
| `schemas/` | JSON schemas for each entity type |

At the root are `README.md` (start here), `AGENTS.md` (how an AI should read the Repo), `CHANGELOG.md` and a `.dutygraph/` folder with generated files such as the [Work Map](work-map.md) projection. The `attestations/`, `changes/` and `decisions/` folders are named but not compiled yet.

## File states

| State | What it means |
| --- | --- |
| Confirmed | A person with authority confirmed it in DutyGraph. The confirmation is recorded. It is not a signature. |
| Observed | At least one client source backs it. Not every key field is confirmed yet. |
| Inferred | It rests only on research, a draft, a rule or an advisor entry. It needs a client source. |
| Disputed | Sources disagree. The best-supported value is shown. |
| Unknown | DutyGraph searched and found no usable evidence. |
| Proposed | A draft change or agent waits for review. |
| Slot | The file exists. Nothing has filled it yet. |
| Generated | Built from other files, such as an index. Not a fact in itself. |

A percentage shows only on research-backed files, for example "Inferred · 77%". It is the research engine's confidence. Record-backed files show a support line instead, such as "2 of 2 confirmed".

The north-star model also uses the word "Approved". The app has no separate Approved state. A Confirmed file carries `status: approved` and `approval: recorded` in its frontmatter.

## The file format

Each file is Markdown with YAML frontmatter at the top. A Task Card file starts like this (trimmed):

```yaml
id: TSK-3fa85f64
type: task
title: Reconcile vendor statements
status: draft
owner: ROLE-AP-MANAGER
approver: null
duty: DUTY-8c1e02d7
department: DEPT-FINANCE
performer: ROLE-AP-SPECIALIST
```

* **Stable ids.** Every file has an `id` that never changes, even when the title changes. A record-backed id is a prefix plus 8 hex characters, such as `TSK-3fa85f64`. A derived id uses a slug, such as `DEPT-FINANCE`. Fixed files have fixed ids, such as `COMPANY-PROFILE`.
* **`status`.** `approved` for a Confirmed file, `proposed` for a Proposed file, `draft` otherwise.
* **`[[ID]]` links.** Files link to each other by id in double brackets, for example `[[TSK-3fa85f64]]`. The folder indexes map each id to its path. An id that does not resolve is printed as plain code, not as a link.
* **`layer`.** The file's level of the company: `company_market`, `leadership`, `department`, `team` or `work`.
* **Links up, down and across.** DutyGraph computes the links from the records, for example `serves`, `owned_by`, `tasks` and `handoffs`. **Details › LINKS** groups them as Up, Down and Across. A link that rests on a proposal shows as **Proposed**.

## The Layer row

The Layer row highlights one level of the company in the tree: **Company & market**, **Leadership**, **Departments ▾**, **Team** or **Work**. It reads each file's `layer` key. **Org chart** at the end of the row opens the reporting chart. A file's **History** shows how it stood after each capture layer. See [Map the company](index.md).

## To review

Select **To review (N)** in the toolbar. It is one queue, with one decision per card:

* readings from people's answers, to **Accept** or **Reject**;
* proposed duties, Task Cards, handoffs and workflows;
* AI modes, owners and hours that code proposed for Task Cards;
* research findings that need a decision, including a confirmed fact that newer research disagrees with.

Nothing changes until a person accepts it.

## Download your company

Select **Download**. The **Download your company** dialog downloads `<slug>.zip`. It holds every file in the tree, Slots as frontmatter-only files, and two extra files: `.dutygraph/index.json` and `.dutygraph/checksums.json` (a SHA-256 hash for each file).

The zip leaves out private text: evidence text, research excerpts and source links, people's answers and notes, email text, kickoff quotes, private links and tokens. Only members who can download exports see the button. Each download is written to the audit log.

## Reading the Repo from an AI

An advisor's AI can read the Repo over MCP with `get_company_repo_index` and `read_company_repo_file`. Both are read-only. The AI is told to read `README.md` first, then only the files it needs. See [MCP for advisors](../connect/mcp.md).

## Why it matters for governance

Task Cards live in the Repo. The Task Cards an agent request cites are the same records the Repo compiles, and an agent manifest pins each one by its record version and content hash. Agent drafts and requests show in `manifests/` as Proposed.

Holdings never become Repo files.

::: info
**Status.** **Built:** the compiled Repo with 17 folders, 8 states, stable ids, `[[ID]]` links, Up, Down and Across links, the Layer row, History, To review, **Download your company**, and the two MCP read tools. **Simulated:** the sample companies' Repos are built from fictional or illustrative records. **Planned:** **Push to GitHub** (the menu shows "Later"), compiling the `policies/`, `risks/`, `attestations/`, `changes/` and `decisions/` folders, compiling governance rule packs and the holdings import receipt into the Repo, a typed Notes editor, and capture sessions that write straight to Repo files.
:::
