# pi-docgraph

> **Purpose:** Primary documentation entry point for human developers. Introduces the project, explains how to install and use it, and links to detailed documentation.
>
> **Audience:** Human
>
> **Source of Truth:** Codebase (implementation is authoritative)
>
> **Last Updated:** 2026-08-10

## What is pi-docgraph?

**pi-docgraph** is an [AI-native documentation graph](docs/PHILOSOPHY.md) extension for the [Pi coding agent](https://pi.dev/). It turns a project's documentation into a small, interconnected graph that AI agents can navigate efficiently instead of reading everything.

Most repositories keep documentation in a few large files. When an AI agent works on a task, it must load the whole docs folder to find what it needs — which burns tokens, slows down responses, and makes docs harder to maintain. pi-docgraph solves this by structuring documentation so an agent can determine relevance instantly and read only the 1–2 documents it actually needs.

The project is grounded in one core principle: **code is always the source of truth**. Documentation explains, summarizes, and navigates the implementation — it never overrides it.

## Who is it for?

- **Developers** using the [Pi coding agent](https://pi.dev/) who want their AI assistant to work faster and more accurately by keeping documentation well-organized and up to date.
- **Teams** who want a lightweight, code-adjacent documentation workflow with clear ticket tracking, without adopting a heavyweight documentation platform.

## How it helps

- **Saves AI context and tokens** — Agents read only relevant documents, not the entire docs folder, so responses are faster and cheaper.
- **Keeps docs in sync with code** — The `docgraph_init` tool scaffolds a standard doc set, and `docgraph_sync` validates cross-references and refreshes timestamps after changes.
- **Tracks work as tickets** — A Kanban-style board under `docs/tickets/` organizes implementation tickets by status and priority, so the agent knows what to work on next.
- **Gives agents context automatically** — On session start, the extension tells the AI whether the graph is initialized and how to use it.

### Practical use cases

- **Onboard a new (or existing) project** — Run `docgraph_init` to scaffold a consistent documentation structure, then let the agent maintain it.
- **Plan and execute work** — Create tickets with priorities and acceptance criteria (`docgraph_ticket_create`), track them on the board (`/docgraph:tickets`), and update their status as work proceeds.
- **Keep docs trustworthy** — After refactors, run `docgraph_sync` to catch broken links and keep the docs aligned with the implementation.

## What makes it different

- **Graph, not monolith** — Every document has one clear responsibility and links to related docs rather than duplicating content.
- **Metadata-first navigation** — Each document begins with a compact metadata block (purpose, audience, dependencies), so agents judge relevance before reading the body.
- **Built for AI and humans** — `README.md` serves human onboarding while `AGENTS.md` acts as a router for AI agents, with the conventions written out in [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md).
- **Codeless to run** — It's a Pi extension, so setup is a single install command; no separate server or database is required.

## Features

- **Selective retrieval** — AI agents read only the documents relevant to the current task, not the entire docs folder.
- **Ticket-driven workflows** — Kanban-style ticket board under `docs/tickets/` with status tracking, priorities, and acceptance criteria.
- **Code-as-source-of-truth** — Documentation describes the implementation; when they disagree, the code wins.
- **Cross-reference validation** — `docgraph_sync` detects broken links between documents.
- **Metadata-driven navigation** — Every document has a metadata block so agents can determine relevance before reading the body.
- **Context injection** — Automatically informs AI agents about the documentation system via `before_agent_start`.

## Installation

### Prerequisites

- [Node.js](https://nodejs.org/) ≥ 22
- [Pi coding agent](https://pi.dev/) installed

### As a Pi Extension

```bash
pi install npm:@ryanyonzon/pi-docgraph
```

After installation, restart your Pi session. The extension will detect whether the documentation graph has been initialized and inform the AI agent accordingly.

## Quick Start

### 1. Initialize the documentation graph

From within a Pi session, ask the AI agent:

```
Run docgraph_init to scaffold the documentation structure.
```

This creates:

| File | Purpose |
|------|---------|
| `README.md` | Human entry point |
| `AGENTS.md` | AI agent entry point & documentation router |
| `docs/SPEC.md` | What the system does and why |
| `docs/ARCHITECTURE.md` | How the system is built |
| `docs/API.md` | Communication contracts |
| `docs/DESIGN.md` | Design system conventions |
| `docs/ROADMAP.md` | Long-term vision and direction |
| `docs/BACKLOG.md` | Current work queue |
| `docs/tickets/` | Individual implementation tickets |

### 2. Read documentation selectively

```
docgraph_read docs/ARCHITECTURE.md
```

Returns the metadata block and body so the agent can determine relevance at a glance.

### 3. Create a ticket

```
docgraph_ticket_create "Add dark mode support" P2
```

### 4. Sync after code changes

```
docgraph_sync docs/API.md
```

Validates cross-references and updates the `Last Updated` timestamp.

## User Commands

These are slash commands available inside Pi:

| Command | Description |
|---------|-------------|
| `/docgraph:init` | Check if the documentation graph is initialized |
| `/docgraph:sync` | Prompt the agent to validate and update docs |
| `/docgraph:tickets` | Display the Kanban ticket board |
| `/docgraph:graph` | Display the documentation graph structure |

## AI Tools

The extension registers these tools for the AI agent:

| Tool | Description |
|------|-------------|
| `docgraph_init` | Scaffold the documentation structure |
| `docgraph_read` | Read a document's metadata and body |
| `docgraph_sync` | Validate cross-references and update timestamps |
| `docgraph_update` | Modify a document field |
| `docgraph_ticket_create` | Create a new implementation ticket |
| `docgraph_ticket_update` | Update ticket status, priority, or content |
| `docgraph_ticket_list` | List tickets, optionally filtered by status |

## Documentation Philosophy

This extension implements the conventions described in [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md). The core principles are:

1. **Code is the source of truth** — never modify code to match docs.
2. **Selective retrieval** — agents should rarely need more than 1–2 documents per task.
3. **Graph, not monolith** — every document has one clear responsibility.
4. **Metadata-first** — the metadata block tells you whether to keep reading.

## Project Structure

```
pi-docgraph/
├── src/
│   ├── index.ts          # Extension entry point
│   ├── types.ts          # Type definitions
│   ├── utils.ts          # File I/O, metadata parsing, ticket persistence
│   ├── tools/
│   │   ├── doc-init.ts   # docgraph_init implementation
│   │   ├── doc-read.ts   # docgraph_read implementation
│   │   ├── doc-sync.ts   # docgraph_sync implementation
│   │   ├── doc-update.ts # docgraph_update implementation
│   │   ├── ticket-create.ts
│   │   ├── ticket-update.ts
│   │   └── ticket-list.ts
│   ├── commands/
│   │   └── index.ts      # Slash command handlers
│   └── events/
│       └── index.ts      # Event handlers (context injection)
├── test/
│   ├── utils.test.ts     # Link-path, metadata, backlog, ticket, validation tests
│   ├── helpers.ts        # Shared mock Pi and temp-repo test helpers
│   └── <...>.test.ts     # Additional per-module test files
│                        # (tools, commands, events, lifecycle, etc.)
├── package.json
├── tsconfig.json
├── tsconfig.test.json
└── LICENSE
```

## Related Documentation

- [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) — Full documentation conventions

## License

MIT © Ryan Yonzon