1. Write for humans first -- Clear prose that a new developer can read and understand. Agent utility is a side effect of good human writing, not a separate goal.
2. Show, don't just tell -- Use ASCII diagrams for architecture and flow, markdown tables for structured information, and backtick formatting for all file paths, commands, and code references.
3. Five sections, each earning its place -- Every section answers a question a new contributor will ask in their first hour. No speculative sections.
4. State what you can observe, not what you must infer -- Do not fabricate design rationale or assess fragility. If the code doesn't reveal why a decision was made, don't guess.
5. Never include secrets -- The onboarding document is committed to the repository. Never include API keys, tokens, passwords, connection strings with credentials, or any other secret values. Reference environment variable names (

   STRIPE_SECRET_KEY

   ), never their values. If a

   .env

   file contains actual secrets, extract only the variable names.
6. Link, don't duplicate -- When existing documentation covers a topic well, link to it inline rather than re-explaining.

scripts/inventory.mjs

node scripts/inventory.mjs --root .

• Project name, languages, frameworks, package manager, test framework
• Directory structure (top-level + one level into source directories)
• Entry points per detected ecosystem
• Available scripts/commands
• Existing documentation files (with first-heading titles for triage)
• Test infrastructure
• Infrastructure and external dependencies (env files, docker services, detected integrations)
• Monorepo structure (if applicable)

ONBOARDING.md

1. README.md (if exists) -- for project purpose and setup instructions
2. Primary entry points -- the files listed in

   entryPoints

   from the inventory. These reveal what the application does when it starts.
3. Route/controller files -- look for

   routes/

   ,

   app/controllers/

   ,

   src/routes/

   ,

   src/api/

   , or similar directories from the inventory structure. Read the main route file to understand the primary flow.
4. Configuration files that reveal architecture and external dependencies --

   docker-compose.yml

   ,

   .env.example

   ,

   .env.sample

   , database config,

   next.config.*

   ,

   vite.config.*

   , or similar. Only read these if they exist in the inventory. Never read

   .env

   itself -- only

   .env.example

   or

   .env.sample

   templates. Extract variable names only, never values.
5. AGENTS.md or CLAUDE.md (if exists) -- for project conventions and patterns already documented.
6. Discovered documentation -- the inventory's

   docs

   list includes each file's title (first heading). Use those titles to decide which docs are relevant to the five sections without reading them first. Only read the full content of docs whose titles indicate direct relevance. Skip dated brainstorm/plan files unless the focus hint specifically calls for them.

# {Project Name} Onboarding Guide

• Write in second person ("you") -- speak directly to the new contributor
• Use active voice and present tense: "The router dispatches requests to handlers" not "Requests are dispatched by the router to handlers"
• Be direct. Lead sentences with what matters, not with setup: "Run

  bun dev

  to start the server" not "In order to start the development server, you will need to run the following command"
• Match the formality of the codebase. A scrappy prototype gets casual prose. An enterprise system gets more precise language. Read the README and existing docs for tone cues.

• Every sentence should teach the reader something or tell them what to do. Cut any sentence that doesn't.
• Prefer concrete over abstract: "

  src/services/billing.ts

  charges the customer's card" not "The billing module handles payment-related business logic"
• When introducing a term, define it immediately in context. Don't make the reader scroll to a glossary.
• Use the simplest word that's accurate. "Use" not "utilize." "Start" not "initialize." "Send" not "transmit."

• Filler and throat-clearing: "It's important to note that", "As mentioned above", "In this section we will"
• Vague summarization: "This module handles various aspects of..." -- say specifically what it does
• Hedge words when stating facts: "This essentially serves as", "This is basically" -- if you know what it does, say it plainly
• Superlatives and marketing language: "robust", "powerful", "comprehensive", "seamless"
• Meta-commentary about the document itself: "This document aims to..." -- just do the thing

• Use backticks for all file names (

  package.json

  ), paths (

  src/routes/

  ), commands (

  bun test

  ), function/class names, environment variables, and technical terms
• Use markdown headers (

  ##

  ) for the five sections
• Use ASCII diagrams and markdown tables where specified below
• Use bold for emphasis sparingly
• Keep paragraphs short -- 2-4 sentences

---

##

white-space: pre

• ASCII architecture diagrams: Stack boxes vertically instead of laying them out horizontally. Never place more than 2 boxes on the same horizontal line, and keep each box label under 20 characters. This caps diagrams at ~60 chars wide.
• Flow diagrams: Keep file path + annotation under 80 chars. If a description is too long, move it to a line below or shorten it.
• Directory trees: Keep inline

  # comments

  under 30 characters. Prefer brief role descriptions ("Editor plugins") over exhaustive lists ("marks, heatmap, suggestions, collab cursors, etc.").

+------------------+
| Native macOS App |
| (Swift/WKWebView)|
+--------+---------+
         |  bridge
         v
+------------------+
| Editor Engine    |  <-- shared core
| (Milkdown/Yjs)  |
+--------+---------+
         |  Vite build
         v
+------------------+    WebSocket    +----------------+
| Browser Client   |<=============>| Express Server  |
+------------------+               +--------+--------+
                                            |
                                   +--------v--------+
                                   | SQLite + Yjs    |
                                   +-----------------+

project-name/
  src/
    routes/       # HTTP route handlers
    services/     # Business logic
    models/       # Data layer
  tests/          # Test suite
  config/         # Environment and app configuration

| Module | Responsibility |
|--------|---------------|
| `src/routes/` | HTTP request handling and routing |
| `src/services/` | Core business logic |
| `src/models/` | Database models and queries |

• docker-compose.yml

  (databases, caches, message queues)
• Environment variable references in config files or

  .env.example

• Import statements for client libraries (database drivers, API SDKs, cloud storage)
• The inventory's detected frameworks (e.g., Prisma implies a database)

| Dependency | What it's used for | Configured via |
|-----------|-------------------|---------------|
| PostgreSQL | Primary data store | `DATABASE_URL` |
| Redis | Session cache and job queue | `REDIS_URL` |
| Stripe API | Payment processing | `STRIPE_SECRET_KEY` |
| S3 | File uploads | `AWS_*` env vars |

• "Business logic lives in the service layer (

  src/services/

  ), not in route handlers"
• "Authentication runs through middleware in

  src/middleware/auth.ts

  before every protected route"
• "Database access uses the repository pattern -- each model has a corresponding repository class"
• "Background jobs are defined in

  src/jobs/

  and dispatched through a Redis-backed queue"

| Concept | What it means in this codebase |
|---------|-------------------------------|
| `Widget` | The primary entity users create and manage |
| `Pipeline` | A sequence of processing steps applied to incoming data |
| Service layer | Business logic in `src/services/`, not handlers |
| Middleware chain | Requests flow through `src/middleware/` first |

1. Setup -- Prerequisites, install steps, environment config. Draw from README and the inventory's scripts. Format commands in code blocks:

   bun install
   cp .env.example .env
   bun dev

2. Running and testing -- How to start the dev server, run tests, lint. Use the inventory's detected scripts.
3. Common change patterns -- Where to go for the 2-3 most common types of changes. For example:
   • "To add a new API endpoint, create a route handler in

     src/routes/

     and register it in

     src/routes/index.ts

     "
   • "To add a new database model, create a file in

     src/models/

     and run

     bun migrate

     "
4. Key files to start with (for complex projects) -- A table mapping areas of the codebase to specific entry-point files with a brief "why start here" note. This gives a new contributor a concrete reading list instead of staring at a large directory tree. For example:

   | Area | File | Why |
   |------|------|-----|
   | Editor core | `src/editor/index.ts` | All editor wiring |
   | Data model | `src/formats/marks.ts` | The annotation system everything builds on |
   | Server entry | `server/index.ts` | Express app setup and route mounting |

   Skip this for projects with fewer than ~10 source files where the directory tree is already a sufficient reading list.
5. Practical tips (for complex projects) -- If the codebase has areas that are particularly large, complex, or have non-obvious gotchas, surface them as brief contributor tips. These communicate real situational awareness that helps a new contributor avoid pitfalls. For example:
   • "The editor module is ~450KB. Most behavior is wired through plugins in

     src/editor/plugins/

     -- understand the plugin architecture before making editor changes."
   • "The collab subsystem has many guards and epoch checks. Read the test names to understand what invariants are maintained."
   Skip this for simple projects where the codebase is small enough to hold in your head.

docs

Authentication uses token-based middleware -- see

docs/solutions/auth-pattern.md

for the full pattern.

• Every section answers its question without padding or filler
• No secrets, API keys, tokens, passwords, or credential values anywhere in the document
• No fabricated design rationale ("we chose X because...")
• No fragility or risk assessments
• File paths referenced in the document correspond to real files from the inventory
• All file names, paths, commands, code references, and technical terms use backtick formatting
• Document title uses "# {Project Name} Onboarding Guide" format, not the filename
• System-level architecture diagram included for multi-surface projects (skipped for simple libraries/CLIs)
• All code block content (diagrams, trees, flow traces) fits within 80 columns
• ASCII diagrams are present in the architecture and/or primary flow sections
• One flow per distinct surface or user type (architecture drives the count, not an arbitrary number)
• External dependencies and integrations are surfaced in the architecture section (or explicitly noted as absent)
• Tables are used for module responsibilities, domain terms/abstractions, and external dependencies
• Markdown styling is consistent throughout (headers, bold, code blocks, tables)
• Existing docs are linked inline only where directly relevant
• Writing is direct and concrete -- no filler, no hedge words, no meta-commentary about the document
• Tone matches the codebase (casual for scrappy projects, precise for enterprise)

ONBOARDING.md

ONBOARDING.md

AskUserQuestion

request_user_input

ask_user

1. Open the file for review
2. Share to Proof
3. Done

• Open for review -> Open

  ONBOARDING.md

  using the current platform's file-open or editor mechanism
• Share to Proof -> Upload the document:
  bash

  CONTENT=$(cat ONBOARDING.md)
  TITLE="Onboarding: <project name from inventory>"
  RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
  PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')

  Display

  View & collaborate in Proof: <PROOF_URL>

  if successful, then return to the options
• Done -> No further action