docentic

Your agent guide through any JS/TS codebase.

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

Make your repo agent-friendly in one command.

docentic scaffolds a standardized documentation spine into any JS/TS codebase — so any AI agent (Claude, ChatGPT, Cursor, Codex, you-name-it) can land on the repo and immediately know where to look. No more grepping blindly. No more hallucinated paths.

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). ~50 files. Works with any stack in the JS/TS ecosystem.

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)
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.
`--minimal`	Skip the `docs/*` spine; scaffold only `AGENTS.md` + `.agents/` + scripts.
`--spine-only`	Scaffold only `AGENTS.md` + `docs/` + `.agents/` — skip the `research/` pipeline and `scripts/llm-docs/`. Good fit for repos that aren't ready to run the daily maintenance loop yet.
`--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
├── .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, research.sh           Validators + research pipeline
│   └── prompts/                           Per-task agent prompts
├── 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/
    ├── 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, ...)

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
  --force                       Overwrite existing files
  --minimal                     Only infrastructure (skip docs/* skeletons)
  --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>                Claude model (default: 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.

Coming soon:

docentic status — show template state for a repo
docentic update — re-sync the template after a new docentic release

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@main

Inputs (all optional):

- uses: intrepideai/docentic@main
  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.2.0' # pin a specific npm version (default: latest)

Pin to a tag for stability (e.g. intrepideai/docentic@v0.2.0) or pin the npm version: input — both work. @main tracks the latest unreleased commit.

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	Notes
Anthropic (default)	`ANTHROPIC_API_KEY`	Recommended — Claude has the best repo-reasoning we've tested
OpenAI	`OPENAI_API_KEY`
Google	`GEMINI_API_KEY`

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 two smoke tests 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 JS/TS codebase.

Name		Name	Last commit message	Last commit date
Latest commit History 9 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

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 2

Packages

Uh oh!

Contributors

Uh oh!

Languages

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 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

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

`.env` (for `docentic populate`)

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

Packages