@mertyalti/agentia-docs

Agentia Docs keeps Markdown and MDX documentation aligned with a repository. It maps source changes to articles, asks Copado AI (through Agentia) for a small edit, checks the result, and opens a pull request or merge request for a person to review. After that review is merged, it can publish the accepted documentation to Copado AI Knowledge.

It is an oclif plugin for the agentia command. You need Agentia Headless (Agentia CLI >= 1.0.0). The plugin does not change Agentia Headless itself. Authentication and Copado AI credentials stay in the host.

Independent personal project by mert yaltı. Not developed, endorsed, supported or warranted by Copado. Copado and Agentia are trademarks of Copado.

• @mertyalti/agentia-docs
• Usage
• License
• Commands

Usage

$ agentia plugins install @mertyalti/agentia-docs
$ agentia COMMAND
running command...
$ agentia (--version)
@mertyalti/agentia-docs/0.1.2 darwin-arm64 node-v25.9.0
$ agentia --help [COMMAND]
USAGE
  $ agentia COMMAND
...

Requires Node.js 18 or newer, Git, and Agentia CLI (@copado/agentia-cli / Agentia Headless) >= 1.0.0. Optional: gh or glab, signed in, if you want the plugin to open the review. Proprietary software: see LICENSE.md.

The relationship graph library is @mertyalti/agentia-graph. This plugin depends on @mertyalti/[email protected]. agentia docs graph and agentia docs draft are part of this plugin. Inspecting a working tree without a commit is @mertyalti/agentia-graph-cli (agentia graph generate), which does not commit.

Typical split:

$ # Working tree only — not committed
$ agentia graph generate
$ agentia graph report --format both

$ # Documentation branch owns the graph file
$ agentia docs graph
$ agentia docs draft
$ agentia docs sync
$ agentia docs publish

@mertyalti/agentia-docs and @mertyalti/agentia-graph-cli both depend on @mertyalti/agentia-graph. Use the docs plugin when articles and reviews matter; use graph-cli when you only need a local graph.json.

Install

$ agentia plugins install @mertyalti/agentia-docs
$ agentia docs --help

$ npm install @mertyalti/[email protected]
$ agentia plugins install @mertyalti/agentia-docs

Sibling checkout (local development)

$ npm ci
$ npm run build
$ agentia plugins link .
$ agentia docs --help

Run npm run build:graph first if ../agentia-graph is not built yet. Packing never builds: npm run build compiles this plugin only, and prepack is a guard that fails fast if dist/ or oclif.manifest.json is missing or stale. Build the sibling ../agentia-graph explicitly with npm run build:graph when you need it (the typecheck step and check still do). To pack, run npm run pack:ci: npm run build, then npm run manifest (oclif manifest through scripts/oclif.mjs, which sets OCLIF_SKIP_NEW_VERSION_CHECK=true for every oclif call, including docs:readme, and sends oclif output to stderr), then npm pack --ignore-scripts. Add -- --json for clean JSON on stdout, or -- --dry-run to list files. Run it from a clean clone or a gate pair, never from a primary or a shared worktree. Never run oclif (or these scripts) with DEBUG=* or DEBUG=update-check in CI: the oclif update check's debug output prints the npm auth header. npm run build (so npm test, check and lint too) first runs scripts/ensure-graph.mjs as prebuild, which runs build:graph only when ../agentia-graph/dist is missing; pack:ci builds with --ignore-scripts, so packing never builds the sibling (on a clone whose graph is not built, pack:ci fails instead). Use npm run --silent pack:ci -- --json for JSON on stdout: without --silent, npm prints its > script banners there. pack:ci leaves oclif.manifest.json in the working tree on purpose (it is gitignored, and a later plain npm pack reuses it); the prepack guard rejects it if it is missing, malformed, for another version, or its command IDs differ from dist/commands. For day-to-day linking you can temporarily use "@mertyalti/agentia-graph": "file:../agentia-graph" instead of the published version.

Agent skills and MCP

Install the documentation-maintainer skill when an agent should use the documentation tools:

$ agentia docs setup skills --target cursor --rules
$ agentia docs setup skills --target agents
$ agentia docs setup skills --target claude

Prefer the plugin-local MCP server for agents (not host MCP injection):

$ agentia docs setup mcp
$ agentia docs mcp start

docs setup mcp writes a Cursor agentia-docs stdio entry (agentia docs mcp start with AGENTIA_PROJECT_ROOT=${workspaceFolder}). Skills prefer MCP tools when that server is connected; CLI --json remains the fallback. Use --force on setup skills only when you intend to overwrite unmanaged skill files. Details: docs/tools.md, docs/guide.md.

Init, sync, publish

The repository needs at least one commit before init. Leave the init files uncommitted. sync copies them onto doc/<source revision> and commits documentation there.

$ agentia docs init --dry-run
$ agentia docs init
$ agentia docs sync
$ agentia docs publish

init turns existing Markdown and MDX into articles. An article with no sources glob is never updated. Each sync updates at most 10 mapped articles. publish opens the review and does not merge it.

| Invocation | Commits to | Documents | | --- | --- | --- | | agentia docs sync | doc/<12-character source revision>, created from the base | Source changes since the merged baseline | | agentia docs sync --target branch | The checked-out branch | Only that branch's own changes | | agentia docs sync --target baseline | The checked-out branch | Everything since the merged baseline | | agentia docs sync --target baseline --branch NAME | NAME, created from the base when missing | Everything since the merged baseline |

Sync does not rebase and does not force-push. When the base moves past an unmerged documentation branch, sync stops with DOC_BRANCH_CANNOT_BE_BEHIND.

$ agentia docs analyze
$ agentia docs status
$ agentia docs validate
$ agentia docs audit
$ agentia docs sync --publish

Configuration

Configuration is .agentia/docs.yaml, or agentia-docs.yaml at the repository root when .gitignore excludes .agentia/. Choose the location with agentia docs init --location agentia|root.

Field reference: docs/configuration.md. Longer start, brownfield, and troubleshooting notes: docs/guide.md.

Graph and draft

agentia docs graph rebuilds the relationship graph from the base revision and commits the graph file on doc/<source revision> when it changed. It does not write articles. --no-prompt fails instead of asking when a documentation branch is behind the base. --target is not supported. The default file is .agentia/docs-graph.json, or agentia-docs-graph.json next to a root config.

agentia docs draft writes feature articles from that stored graph onto doc/<source revision>. It does not rebuild the graph. A missing graph, or a built_at_commit that is not the revision being documented, is reported. --no-human creates eligible articles without questions (matching declines are skipped). --target is not supported.

$ agentia docs graph
$ agentia docs draft
$ agentia docs draft --no-human

For a working-tree graph.json that is never committed, use @mertyalti/agentia-graph-cli (agentia graph generate).

Knowledge

agentia docs knowledge sync reads the accepted base revision with git show. It does not read the working tree or an unmerged branch.

• export (default) writes accepted documents and a manifest.json under .agentia/docs-local/knowledge-export/. No credential.
• copado-api uploads to a Copado AI dataset. It needs AGENTIA_AI_PAK in the environment. Do not commit that value.

A failed knowledge sync does not undo merged documentation. See docs/destinations.md.

Brownfield and further reading

Existing documentation trees, protected blocks, mapping triage, and recovery after a behind branch are covered in docs/guide.md. Command flags and error codes: docs/cli.md. Tool commands for agents (docs changes, docs affected, docs catalog, docs source, docs article): docs/tools.md. Architecture and security: docs/architecture.md, docs/security.md. Build and tests: docs/development.md.

Every command accepts --json unless noted in the command reference below.

License

Copyright (c) mert yaltı. All rights reserved. See LICENSE.md. Permission is granted to install and use this software with Agentia Headless; redistribution, sublicensing, and modification require prior written permission.

Commands

• agentia docs affected
• agentia docs analyze
• agentia docs article read ARTICLE
• agentia docs article validate ARTICLE
• agentia docs article write ARTICLE
• agentia docs audit
• agentia docs catalog
• agentia docs changes
• agentia docs draft
• agentia docs graph
• agentia docs init
• agentia docs knowledge sync
• agentia docs publish
• agentia docs setup skills
• agentia docs source read PATH
• agentia docs source search QUERY
• agentia docs status
• agentia docs sync
• agentia docs validate

agentia docs affected

Determine articles affected by changed files (tool: docs_get_affected_articles)

USAGE
  $ agentia docs affected [--json] [--file <value>...] [--no-ai]

FLAGS
  --file=<value>...  Changed file to map (defaults to pending changes)
  --no-ai            Deterministic mappings only

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Determine articles affected by changed files (tool: docs_get_affected_articles)

EXAMPLES
  $ agentia docs affected --json

  $ agentia docs affected --file src/auth/token.py --no-ai

agentia docs analyze

Preview mapped changes and feature proposals from the stored relationship graph

USAGE
  $ agentia docs analyze [--json] [--no-ai] [--no-fetch]

FLAGS
  --no-ai     Accepted for compatibility. Analyze never calls Copado AI.
  --no-fetch  Do not fetch the base branch before analyzing

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Preview mapped changes and feature proposals from the stored relationship graph

  Lists changed files since the documented baseline and the existing article each file maps to, using catalog globs
  only. It also reads the stored relationship graph and prints eligible features, declined features, hub files, and
  files that are not a source of any in-scope feature. A missing or stale graph is reported; this command does not
  rebuild it and does not call Copado AI.

EXAMPLES
  $ agentia docs analyze

  $ agentia docs analyze --json

agentia docs article read ARTICLE

Read one documentation article (tool: docs_read_article)

USAGE
  $ agentia docs article read ARTICLE [--json]

ARGUMENTS
  ARTICLE  Article id from the catalog

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Read one documentation article (tool: docs_read_article)

EXAMPLES
  $ agentia docs article read authentication --json

agentia docs article validate ARTICLE

Validate one article and return structured errors (tool: docs_validate_article)

USAGE
  $ agentia docs article validate ARTICLE [--json] [--against <value>]

ARGUMENTS
  ARTICLE  Article id from the catalog

FLAGS
  --against=<value>  Git ref whose protected blocks must be preserved (defaults to the base branch)

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Validate one article and return structured errors (tool: docs_validate_article)

EXAMPLES
  $ agentia docs article validate authentication --json

agentia docs article write ARTICLE

Modify one article in the working tree with validated minimal edits or full content (tool: docs_write_article)

USAGE
  $ agentia docs article write ARTICLE [--json] [--content-file <value> | --edits-file <value>]

ARGUMENTS
  ARTICLE  Article id from the catalog

FLAGS
  --content-file=<value>  File with the full article content ("-" for stdin)
  --edits-file=<value>    JSON file with [{"old": "...", "new": "..."}] edits ("-" for stdin)

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Modify one article in the working tree with validated minimal edits or full content (tool: docs_write_article)

EXAMPLES
  $ agentia docs article write authentication --edits-file edits.json

  cat new.md | agentia docs article write authentication --content-file -

agentia docs audit

Find documentation drift that sync will not notice on its own

USAGE
  $ agentia docs audit [--json]

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Find documentation drift that sync will not notice on its own

  Run this when sync reports no changes but the documentation may still be wrong, or before a release. It reports stale
  articles, source no article maps, broken mappings, broken links, terminology that disagrees with the config, and
  Markdown missing from the catalog. It does not update anything.

EXAMPLES
  $ agentia docs audit

  $ agentia docs audit --json

agentia docs catalog

Show the documentation catalog and source mappings (tool: docs_get_catalog)

USAGE
  $ agentia docs catalog [--json]

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Show the documentation catalog and source mappings (tool: docs_get_catalog)

EXAMPLES
  $ agentia docs catalog

  $ agentia docs catalog --json

agentia docs changes

List source changes since the last accepted documentation point (tool: docs_get_changes)

USAGE
  $ agentia docs changes [--json] [--since <value>]

FLAGS
  --since=<value>  Override the starting revision

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  List source changes since the last accepted documentation point (tool: docs_get_changes)

EXAMPLES
  $ agentia docs changes --json

  $ agentia docs changes --since HEAD~5

agentia docs draft

Write feature articles from the stored relationship graph

USAGE
  $ agentia docs draft [--json] [--no-fetch] [--no-human]

FLAGS
  --no-fetch  Do not fetch the base branch before drafting
  --no-human  Create eligible articles without questions. A matching decline is skipped. A changed decline is reported
              and skipped.

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Write feature articles from the stored relationship graph

  Proposes one article per in-scope Copado feature and, after a Yes, writes it into the Features section. The commit
  lands on doc/<source revision>. A missing or stale graph is reported and is not rebuilt. --no-human creates articles
  without questions, skips a decline whose digest still matches, and reports a changed decline without creating the
  article. --target is not supported.

EXAMPLES
  $ agentia docs draft

  $ agentia docs draft --no-human

agentia docs graph

Rebuild the stored relationship graph and commit it on doc/

USAGE
  $ agentia docs graph [--json] [--no-prompt]

FLAGS
  --no-prompt  Fail immediately when a documentation branch is behind the base. Does not ask to delete it, and does not
               start the graph walk.

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Rebuild the stored relationship graph and commit it on doc/<source revision>

  Walks the full source tree at the base revision and commits the graph file on doc/<source revision>. The current
  checkout is left unchanged. The commit includes only that file. It does not write articles or change
  documented_revision. When a documentation branch is behind the base, a terminal asks before deleting it. --no-prompt
  fails immediately instead. --target is not supported.

EXAMPLES
  $ agentia docs graph

  $ agentia docs graph --json

  $ agentia docs graph --no-prompt

agentia docs init

Discover documentation and source layout, then write a reviewable configuration (.agentia/docs.yaml or agentia-docs.yaml), catalog, and baseline state

USAGE
  $ agentia docs init [--json] [--ai] [--docs-root <value>] [--dry-run] [--force] [--location agentia|root]

FLAGS
  --ai                 Ask Copado AI (through Agentia) to propose additional source mappings
  --docs-root=<value>  Documentation root directory (auto-detected by default)
  --dry-run            Print the proposed configuration without writing files
  --force              Overwrite existing Agentia Docs configuration, catalog, and state
  --location=<option>  Where the committed configuration and state live: "agentia" (.agentia/docs.yaml,
                       .agentia/docs-state.json) or "root" (agentia-docs.yaml, agentia-docs-state.json). Defaults to
                       agentia unless .gitignore excludes .agentia/
                       <options: agentia|root>

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Discover documentation and source layout, then write a reviewable configuration (.agentia/docs.yaml or
  agentia-docs.yaml), catalog, and baseline state

EXAMPLES
  $ agentia docs init --dry-run

  $ agentia docs init

  $ agentia docs init --docs-root website/docs --ai

  $ agentia docs init --location root

agentia docs knowledge sync

Synchronize accepted (merged) documentation from the base branch into Copado AI Knowledge

USAGE
  $ agentia docs knowledge sync [--json] [--dry-run]

FLAGS
  --dry-run  Show what would be created, updated, or deleted

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Synchronize accepted (merged) documentation from the base branch into Copado AI Knowledge

EXAMPLES
  $ agentia docs knowledge sync

  $ agentia docs knowledge sync --dry-run --json

agentia docs publish

Push the documentation branch and create or update its PR/MR for human review (never merges)

USAGE
  $ agentia docs publish [--json]

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Push the documentation branch and create or update its PR/MR for human review (never merges)

EXAMPLES
  $ agentia docs publish

  $ agentia docs publish --json

agentia docs setup skills

Install the Agentia Docs agent skill (and optional Cursor rule) into this project

USAGE
  $ agentia docs setup skills [--json] [--force] [--rules] [--target agents|cursor|claude...]

FLAGS
  --force               Replace skill files that are not managed by Agentia Docs
  --rules               Also install .cursor/rules/agentia-docs.mdc
  --target=<option>...  [default: agents] Skill root to install into
                        <options: agents|cursor|claude>

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Install the Agentia Docs agent skill (and optional Cursor rule) into this project

EXAMPLES
  $ agentia docs setup skills

  $ agentia docs setup skills --target cursor --target claude --rules

agentia docs source read PATH

Read an approved source or documentation file (tool: docs_read_source)

USAGE
  $ agentia docs source read PATH [--json] [--end <value>] [--start <value>]

ARGUMENTS
  PATH  Repository-relative file path

FLAGS
  --end=<value>    Last line to read
  --start=<value>  First line to read

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Read an approved source or documentation file (tool: docs_read_source)

EXAMPLES
  $ agentia docs source read src/auth/token.py

  $ agentia docs source read src/app.ts --start 10 --end 80 --json

agentia docs source search QUERY

Search approved repository files with bounded results (tool: docs_search_source)

USAGE
  $ agentia docs source search QUERY [--json] [--glob <value>] [--max-results <value>] [--regex]

ARGUMENTS
  QUERY  Text (or regular expression with --regex) to search for

FLAGS
  --glob=<value>         Restrict to files matching this glob
  --max-results=<value>  Maximum hits (1-100)
  --regex                Treat the query as a regular expression

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Search approved repository files with bounded results (tool: docs_search_source)

EXAMPLES
  $ agentia docs source search issueToken

  $ agentia docs source search "def \w+_token" --regex --glob "src/**"

agentia docs status

See whether the docs branch, the review, and knowledge are behind the source

USAGE
  $ agentia docs status [--json] [--no-fetch]

FLAGS
  --no-fetch  Do not fetch the base branch first

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  See whether the docs branch, the review, and knowledge are behind the source

  Run this when you are unsure which command comes next. It shows the source revision, the last documented revision,
  pending source changes, the docs branch and pull request, the last validation result, and whether Copado AI Knowledge
  matches the merged documentation.

EXAMPLES
  $ agentia docs status

  $ agentia docs status --json

agentia docs sync

Update affected documentation with Agentia and Copado AI: analyze, update, validate, consistency pass, and commit. Without --target the commit lands on doc/, created from the base branch.

USAGE
  $ agentia docs sync [--json] [--branch <value>] [--keep-worktree] [--no-fetch] [--publish] [--target
    branch|baseline]

FLAGS
  --branch=<value>   With --target baseline: branch to commit to, created from the base when missing. Fails when the
                     base has moved past it.
  --keep-worktree    When sync fails, keep the temporary worktree and its branch for inspection instead of removing
                     them. On a commit failure a terminal also asks whether to bring the generated documentation onto
                     the current branch; decline and this flag leaves the worktree in place. Remove it afterwards with
                     "git worktree remove --force <dir>".
  --no-fetch         Do not fetch the base and documentation branches first
  --publish          Run "docs publish" after a successful sync
  --target=<option>  branch: commit to the checked-out branch, documenting only its changes. baseline: full
                     documentation. Omit for doc/<source revision>.
                     <options: branch|baseline>

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Update affected documentation with Agentia and Copado AI: analyze, update, validate, consistency pass, and commit.
  Without --target the commit lands on doc/<source revision>, created from the base branch.

EXAMPLES
  Commit to doc/<source revision> from the base branch

    $ agentia docs sync

  Document the checked-out branch's own source changes on that branch

    $ agentia docs sync --target branch

  Full documentation on the checked-out branch, for example a pull request pipeline

    $ agentia docs sync --target baseline

  Scheduled job: full documentation on a branch your naming rules allow

    $ agentia docs sync --target baseline --branch feature/docs-baseline --publish --json

agentia docs validate

Check links, mappings, protected blocks, and structure without calling Copado AI

USAGE
  $ agentia docs validate [--json] [--against <value>] [--article <value>...] [--ref <value>]

FLAGS
  --against=<value>     Git ref whose protected blocks must be preserved (defaults to the base branch on the docs
                        branch)
  --article=<value>...  Validate only this article id
  --ref=<value>         Validate the content of a Git ref instead of the working tree

GLOBAL FLAGS
  --json  Format output as json.

DESCRIPTION
  Check links, mappings, protected blocks, and structure without calling Copado AI

  Run this when publish refuses the docs branch, or after you edit an article by hand. It checks internal links, source
  mappings, protected blocks, and structure, and exits with an error when a check fails. Use --ref <branch> to check the
  branch sync wrote (sync prints it). Publish runs the same checks.

EXAMPLES
  $ agentia docs validate

  $ agentia docs validate --article authentication

  $ agentia docs validate --ref doc/1a2b3c4d5e6f --against origin/main