docentic

Your agent guide through any codebase.

Quick start · Why · What you get · Commands · Give to your AI

Make your repo agent-friendly in one command.

docentic reads your codebase and writes the real facts — your actual routes, data models, endpoints, and dependencies — into a standardized doc spine that any AI agent (Claude, Cursor, Codex, Gemini, you-name-it) reads first. Not boilerplate, not empty templates: on supported stacks the first run fills your docs from the code, so your AI stops hallucinating paths and breaking what already works.

Every repo in your fleet gets the same shape, so any agent (or human) lands somewhere new and instantly knows where to look.

Just exported from Lovable, Bolt, v0, or Replit? npx @intrepideai/docentic init makes that fresh repo agent-ready in one step.

Scope, honestly: the scaffold and LLM content-fill (docentic populate) work on any repo. The deterministic generators that fill docs from code (STACK / API / DATA / MAP / INTEGRATIONS) ship real extractors for JS/TS (Next.js · Express · Fastify · Hono), Python (FastAPI · Flask · Django), Go (gin · chi · echo), Ruby (Rails), and PHP (Laravel) — with Prisma/Drizzle, SQLAlchemy/Django ORM, GORM, ActiveRecord, and Eloquent. Other stacks get the full spine with honest placeholders you fill via docentic populate or your agent.

A docent guides visitors through a museum. docentic does the same for your repo — for both humans and AI agents. (The name is the adjective form: tools that are docentic are tools that act like a docent.)

Three ways to start — pick one and copy

1. In your terminal

npx @intrepideai/docentic init

That commits a docentic/template-scaffold branch and opens a PR (if gh is configured). A lean spine (~30 files) — and on supported stacks the generated docs come pre-filled from your code, not as empty TODOs. Add --full if you also want the research/ pipeline. Works on any repo (see Scope).

2. In any agent with repo filesystem access (Claude Code · Cursor agent · Codex CLI · Gemini CLI · …)

Make the repo at <YOUR-REPO-PATH> agent-friendly using docentic (https://github.com/intrepideai/docentic).

1. cd to that path.
2. Run: npx @intrepideai/docentic init --no-pr
3. Read https://github.com/intrepideai/docentic/blob/main/prompts/bootstrap.md and follow it — fill all the TODO markers in AGENTS.md and docs/*.md by reading the codebase.
4. Commit on a branch and open a PR titled "chore: populate docentic scaffold with real content".

Begin.

Replace <YOUR-REPO-PATH> with your repo's path. Your agent runs scaffold + content fill + PR in one shot.

Heads up: this path needs an agent that can shell out and edit files — Claude Code, Cursor's agent mode, Codex CLI, Gemini CLI, OpenHands, Aider, etc. Stock chat surfaces (ChatGPT, Claude.ai web) don't have repo access and won't be able to run step 2. For those, use option 1 in your terminal first, then paste prompts/bootstrap.md into chat with the relevant file contents.

3. In your editor (Claude Code or Cursor)

# One-time install of the docentic skill
npx @intrepideai/docentic install

Then in any Claude Code or Cursor chat:

"docentic this repo"

Your agent picks it up automatically — scaffolds, then offers to fill the content TODOs. Two messages, end-to-end.

Bonus — full auto with an API key

echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
npx @intrepideai/docentic init && npx @intrepideai/docentic populate

The scaffold + content fill done by the CLI itself. No chat, no prompts to paste. Costs ~$0.30 per repo.

Why

Stock repos are unreadable to AI agents. README is for humans, intent lives in heads, and architectural decisions evaporate. Agents end up grepping the wrong file three times before giving up.

Without docentic

You: "What's the data model?"
Agent: *greps for "model"*
        *finds 47 matches in node_modules*
        *hallucinates a schema*

With docentic

You: "What's the data model?"
Agent: *reads AGENTS.md → docs/DATA.md*
        *quotes the actual schema with line numbers*
        *links back to ARCHITECTURE.md for context*

Concern	Stock repo	With docentic
Entry point	README.md (for humans)	`AGENTS.md` (for agents)
Architecture intent	In someone's head	`docs/ARCHITECTURE.md` (the anchor)
Data model	Scattered across migrations	`docs/DATA.md` (auto-regenerated)
API surface	Greppable, sometimes	`docs/API.md` (auto-regenerated)
Known decisions	Buried in PR threads	`docs/DECISIONS.md` (ADRs)
What changed lately	`git log` (verbose)	`docs/HISTORY.md` (curated)
External research	None	`research/` (compounds over time — opt in with `--full`)
Update cycle	Manual, drifts	Automated via the `maintain-repo` skill

The whole point: same shape across every repo in your fleet, so any agent (or human) lands somewhere new and instantly knows what to do.

Full walkthrough

The quick-start commands above handle 90% of repos. Here's the longer version with every option.

1. Install (or skip — use `npx`)

# Zero-install one-shot (recommended)
npx @intrepideai/docentic init

# Or install globally
npm install -g @intrepideai/docentic
docentic init

# Or clone for development
git clone git@github.com:intrepideai/docentic.git
cd docentic && npm install && npm run build && npm link

Useful flags

Flag	What it does
`--dry-run`	Print what would be created and exit; touch nothing.
`--full`	Also scaffold the `research/` pipeline (scouts + daily research loop). Off by default — the lean spine covers most repos; opt in when you're ready to run the research loop.
`--minimal`	Skip the `docs/*` spine; scaffold only `AGENTS.md` + `.agents/` + scripts.
`--spine-only`	Scaffold only `AGENTS.md` + `docs/` + `.agents/` — skip `scripts/llm-docs/` and the research pipeline. Good fit for repos that just want the doc spine.
`--force`	Overwrite existing files. By default, anything that already exists is skipped.
`--force-ignored`	Scaffold a file even if `.gitignore` would drop it on `git add`. (Default: hard-stop with the list, so you can fix `.gitignore` first.)
`--no-pr`	Commit on a branch, but don't open a PR.
`--no-commit`	Write files in place, skip git operations entirely.

docentic init is safe to re-run. Existing files are skipped unless you pass --force, so you can run it again to pick up template updates without clobbering local edits.

2. Fill the content

The scaffold leaves TODO markers in AGENTS.md and docs/*.md — real content depends on your codebase. Two ways:

Manual mode (filesystem-capable agent, no API key needed): paste prompts/bootstrap.md — or the shorter prompt from the hero section — into Claude Code, Cursor's agent mode, Codex CLI, Gemini CLI, OpenHands, or any other agent that can read and write your repo's files directly. (Stock ChatGPT and Claude.ai web won't work here — they can't see your filesystem.)
Automated mode: copy .env.example → .env, add ANTHROPIC_API_KEY, then docentic populate.

3. Schedule maintenance

Once content is filled, schedule the 5 daily-cadence agents (Scout, Researcher, Librarian, HISTORY Writer, Conflict Resolver) to point at the repo. The agents keep docs fresh, surface external research, and never silently overwrite human edits.

What you get

The repo gains a hub-and-spoke documentation graph. ARCHITECTURE.md is the hub; everything else points back. Agents that lose context have a guaranteed re-orient path.

graph TD
    A[AGENTS.md<br/>root index] --> B((ARCHITECTURE.md<br/>system anchor))

    B --> S[STACK.md]
    B --> D[DATA.md]
    B --> AP[API.md]
    B --> M[MAP.md]
    B --> I[INTEGRATIONS.md]
    B --> O[OPS.md]
    B --> C[CONVENTIONS.md]
    B --> G[GLOSSARY.md]
    B --> SEC[SECURITY-NOTES.md]
    B --> DEC[DECISIONS.md]
    B --> H[HISTORY.md]

    A -.auto-detected.-> UI[UI.md]
    A -.auto-detected.-> INF[INFRA.md]
    A -.auto-detected.-> ML[ML.md]
    A -.auto-detected.-> MOB[MOBILE.md]

    A --> R{{research/}}
    R --> RC[config.yml]
    R --> RT[topics/]
    R --> RM[_meta/<br/>6 daily views]

    classDef generated fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    classDef manual fill:#f5f3ff,stroke:#a78bfa,color:#1e1b4b,stroke-dasharray: 5 5
    classDef ai fill:#7c3aed,stroke:#5b21b6,color:#fff
    classDef anchor fill:#7c3aed,stroke:#5b21b6,color:#fff,stroke-width:3px

    class B anchor
    class S,D,AP,M,I generated
    class O,C,G,SEC,DEC,UI,INF,ML,MOB,A manual
    class H ai

Legend: purple solid = auto-regenerated · purple dashed = manual · solid filled = AI-maintained · ARCHITECTURE.md = the anchor.

Or as a raw file tree

your-repo/
├── AGENTS.md                              Root index — every agent reads this first
├── CLAUDE.md                              Thin pointer that imports AGENTS.md (Claude Code reads this)
├── .agents/
│   ├── index.json                         Machine-readable doc inventory
│   └── REMOVALS.md                        Permanent audit log of deletions
├── .claude/skills/maintain-repo/
│   └── SKILL.md                           Claude Code wrapper
├── scripts/llm-docs/
│   ├── MAINTAIN.md                        The orchestrator spec
│   ├── gen-*.sh                           Deterministic doc generators
│   ├── validate.sh                        Structure + drift validators
│   ├── research.sh                        Research pipeline driver (--full only)
│   └── prompts/                           Per-task agent prompts (--full only)
├── docs/
│   ├── ARCHITECTURE.md                    THE ANCHOR — everything else points here
│   ├── STACK / DATA / API / MAP           Auto-regenerated
│   ├── INTEGRATIONS / OPS                 Manual, critical
│   ├── CONVENTIONS / GLOSSARY             Manual, auto-merge after 24h
│   ├── SECURITY-NOTES / DECISIONS         Manual, critical (review required)
│   ├── HISTORY                            AI-maintained, auto-merge after 4h
│   └── UI / INFRA / ML / MOBILE           Auto-detected based on stack
└── research/                             (only with --full)
    ├── config.yml                         Topics & sources (one repo-specific file)
    ├── intake/                            Scout output queue
    ├── topics/                            Research files organized by topic
    └── _meta/                             6 daily-rebuilt views (digest, top, gaps, ...)

The lean default scaffolds everything above except research/ — pass --full to add the research pipeline. The generated docs (STACK / API / DATA / MAP / INTEGRATIONS) are filled from your code on the first run for JS/TS, Python, Go, Ruby & PHP; other stacks get honest placeholders.

Stack detection automatically adds UI.md for frontends, INFRA.md for IaC repos, ML.md for ML, MOBILE.md for mobile.

Commands

docentic init [path]              Scaffold the template into a repo
  --dry-run                     Show what would be created without writing
  --full                        Also scaffold the research/ pipeline (off by default)
  --force                       Overwrite existing files
  --minimal                     Only infrastructure (skip docs/* skeletons)
  --spine-only                  Only AGENTS.md + docs/ + .agents/ (no scripts, no research)
  --no-pr                       Commit on a branch but don't open a PR
  --no-commit                   Just write files; no git operations
  --branch <name>               Custom branch name (default: docentic/template-scaffold)

docentic populate [path]          Fill scaffolded TODOs using an LLM
  --model <name>                model id (default: provider's default, e.g. claude-sonnet-4-6)
  --max-cost <usd>              Abort if estimated cost exceeds this (default: 5)
  --no-pr                       Commit on a branch but don't open a PR
  --no-commit                   Apply edits without git operations
  --branch <name>               Custom branch name (default: docentic/populate-content)
  --dry-run                     Gather context + estimate cost without calling the API

docentic check [path]             Validate a docentic-scaffolded repo (no writes)
  --json                        Output JSON instead of text (for tooling)
  --warnings-as-errors          Fail on warnings — strict CI mode

docentic install                  Install the docentic skill into Claude Code and/or Cursor
  --claude                      Install only the Claude Code skill
  --cursor                      Install only the Cursor rule
  --project <path>              For Cursor: install per-project instead of globally
  --force                       Overwrite if already installed
  --dry-run                     Show what would be installed without writing

Exit codes for docentic check: 0 healthy · 1 errors found · 2 not a docentic repo.

docentic check validates structure (schema + required files), catches broken doc references and leftover TODO markers, and flags content drift from the recorded hash. The last three are warnings by default, so a freshly-scaffolded repo (and everyday use) passes. --warnings-as-errors turns them into failures — the strict gate to add to CI once your docs are filled: it fails on leftover TODOs, broken references, or drift. (A fresh, not-yet-filled scaffold intentionally fails strict mode — that's the "you still have TODOs" signal.)

docentic init is safe to re-run to pick up template updates (existing files are skipped unless --force).

Editor install (Claude Code · Cursor)

For deeper detail on the editor skill — manual install paths, what triggers it, what it does — see the installation guide at the top, plus the source files: skills/claude/SKILL.md · skills/cursor/docentic.mdc.

Use it in CI

Available on the GitHub Marketplace. Drop this into .github/workflows/docentic.yml to fail PRs that break the scaffold (broken .agents/index.json, missing spine files, schema violations):

name: docentic check
on:
  pull_request:
  push:
    branches: [main]

jobs:
  docentic-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: intrepideai/docentic@v0.4.0   # pin a tag (recommended)

Inputs (all optional):

- uses: intrepideai/docentic@v0.4.0
  with:
    path: '.'                              # repo path to check (default: workspace root)
    warnings-as-errors: 'true'             # fail on warnings too (default: false)
    json: 'false'                          # output JSON for piping (default: false)
    node-version: '20'                     # Node version to install (default: 20, min 20)
    version: '@intrepideai/docentic@0.4.0' # pin a specific npm version (default: latest)

Pin to a tag (e.g. intrepideai/docentic@v0.4.0) for reproducible CI — recommended. You can also pin the npm version: input. @main tracks the latest unreleased commit (use only if you want the bleeding edge).

Outputs:

Output	Description
`ok`	`"true"` if check passed, `"false"` otherwise — handy for `if: steps.docentic.outputs.ok == 'false'`
`check-summary`	One-line summary like `errors=2 warnings=1 spine_missing=0` — pipe into a PR comment or Slack message

Example: post the summary to the PR on failure:

- id: docentic
  uses: intrepideai/docentic@main
  continue-on-error: true

- if: steps.docentic.outputs.ok == 'false'
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        ...context.repo,
        issue_number: context.issue.number,
        body: `🟣 docentic: ${{ steps.docentic.outputs.check-summary }} — see [Actions log](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})`
      })

Schemas (for tools and IDEs)

.agents/index.json ships with a JSON Schema. The scaffolded template includes a $schema reference, so editors with JSON Schema support (VS Code, Cursor, etc.) get autocomplete + validation out of the box.

Schema URL: https://raw.githubusercontent.com/intrepideai/docentic/main/schemas/agents-index.schema.json

To validate by hand:

# Using ajv-cli
npx -y ajv-cli validate \
  -s https://raw.githubusercontent.com/intrepideai/docentic/main/schemas/agents-index.schema.json \
  -d .agents/index.json

Or just run docentic check — it does this validation built-in.

How it fits with agents

docentic handles scaffolding only. Day-to-day maintenance — refreshing generated docs, surfacing research, updating HISTORY — runs as a separate agent loop you schedule externally (Claude Desktop tasks, cron + a harness, your platform of choice).

Prompts split by job:

prompts/bootstrap.md — one-shot content fill (after docentic init)
prompts/config-seeder.md — propose tailored research/config.yml
Daily maintenance (Scout / Researcher / Librarian / HISTORY Writer / Conflict Resolver) — see Intrepide's orchestrator library

Configuration

`.env` (for `docentic populate`)

Copy .env.example to .env and fill in one of:

Provider	Var	Model API	Notes
Anthropic (default)	`ANTHROPIC_API_KEY`	Messages + tool use	Recommended — Claude has the best repo-reasoning we've tested
OpenAI	`OPENAI_API_KEY`	Chat Completions + function calling	Honors `OPENAI_MODEL` and `OPENAI_BASE_URL` (Azure / compatible gateways)
Google	`GEMINI_API_KEY`	`generateContent` + function calling	Honors `GEMINI_MODEL`

populate picks the provider from DOCENT_PROVIDER if set, otherwise the first key present (Anthropic → OpenAI → Gemini). docentic init itself needs no API keys — it's pure scaffolding.

`research/config.yml` (per-repo)

The one file that's truly repo-specific. Topics, keywords, sources, cadence. Run prompts/config-seeder.md to get a tailored proposal based on your codebase.

Design principles

Hub-and-spoke docs. Every file points back to ARCHITECTURE.md. Agents that lose context have a guaranteed re-orient path.
Three content tiers. generated (deterministic), manual (human-owned), ai (narrow agent updates with NO_UPDATE_NEEDED exit).
Hash-based safety. Generated files have a generated_hash stored. Manual edits trigger a conflict PR instead of being silently overwritten.
Lean over comprehensive. Spec files orient and summarize; heavy data stays in code, configs, vendor docs. Less drift.
Critical files always reviewed. AGENTS.md, ARCHITECTURE.md, OPS.md, SECURITY-NOTES.md, DECISIONS.md never auto-merge.

Show your repo is agent-friendly

If you've scaffolded docentic, add the badge to your README so other agents and humans know:

[![agent-friendly: yes](https://img.shields.io/badge/agent--friendly-yes-7c3aed?style=flat-square)](https://github.com/intrepideai/docentic)

Renders as:

Local development

git clone git@github.com:intrepideai/docentic.git
cd docentic
npm install
npm run dev -- init /path/to/test/repo --dry-run    # iterate
npm run build && npm link                            # try the binary

CI (.github/workflows/ci.yml) typechecks, runs the node:test + smoke-test suite, and runs the generator shell tests (grep + ripgrep paths, Node 20/22) on every PR.

Contributing

Contributions welcome — docentic is a tiny tool with a tight scope, so PRs that fit are easy to land.

Read CONTRIBUTING.md for setup, scope, and PR conventions
See SECURITY.md to report a vulnerability privately
By participating you agree to the Code of Conduct
Notable changes are tracked in CHANGELOG.md

Star the repo if docentic is useful — it genuinely helps with discoverability.

License

Apache License 2.0. Use it commercially, fork it, modify it, redistribute it — just keep the license + notice files intact.

Made by Intrepide. Built for any agent, any LLM, any codebase.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

docentic

Three ways to start — pick one and copy

1. In your terminal

2. In any agent with repo filesystem access (Claude Code · Cursor agent · Codex CLI · Gemini CLI · …)

3. In your editor (Claude Code or Cursor)

Bonus — full auto with an API key

Why

Without docentic

With docentic

Full walkthrough

1. Install (or skip — use `npx`)

Useful flags

2. Fill the content

3. Schedule maintenance

What you get

Commands

Editor install (Claude Code · Cursor)

Use it in CI

Schemas (for tools and IDEs)

How it fits with agents

Configuration

`.env` (for `docentic populate`)

`research/config.yml` (per-repo)

Design principles

Show your repo is agent-friendly

Local development

Contributing

License

About

Uh oh!

Releases 3

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github		.github
docs/assets		docs/assets
prompts		prompts
schemas		schemas
skills		skills
src		src
templates		templates
test		test
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
action.yml		action.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

docentic

Three ways to start — pick one and copy

1. In your terminal

2. In any agent with repo filesystem access (Claude Code · Cursor agent · Codex CLI · Gemini CLI · …)

3. In your editor (Claude Code or Cursor)

Bonus — full auto with an API key

Why

Without docentic

With docentic

Full walkthrough

1. Install (or skip — use npx)

Useful flags

2. Fill the content

3. Schedule maintenance

What you get

Commands

Editor install (Claude Code · Cursor)

Use it in CI

Schemas (for tools and IDEs)

How it fits with agents

Configuration

.env (for docentic populate)

research/config.yml (per-repo)

Design principles

Show your repo is agent-friendly

Local development

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. Install (or skip — use `npx`)

`.env` (for `docentic populate`)

`research/config.yml` (per-repo)

Packages