DokSteward CLI

CI-first AI documentation agent that opens reviewable PRs for README and docs updates.

Docs PRs, not silent commits. Runs in your CI, under your credentials. No hosted repository ingestion by default.

DokSteward helps design partners test a narrow GitHub-first MVP: inspect scoped repository changes, decide whether approved documentation targets need updates, and open a draft documentation PR when a validated update is ready.

Installation

Use Node.js 22 or newer.

Install the CLI in the repository where DokSteward will run:

npm install --save-dev @meisterware/doksteward

Confirm the installed package binary is available from the project lockfile:

npx --no-install doksteward --version

For a one-off evaluation without adding the package first:

npm exec --package @meisterware/doksteward -- doksteward --version

Current Status

v0.7.x is focused on MVP hardening and validation before the public v1.0 release. The supported path remains narrow: CI-local documentation review, validated docs-only changes, and GitHub draft PRs for human review.

What DokSteward Does

DokSteward is built for repository-adjacent docs, not broad autonomous coding. The current MVP path:

• runs locally or in GitHub Actions
• reads doksteward.yml from the repository root
• inspects changed files and approved documentation targets
• builds scoped context for the configured model provider
• optionally safe-stops until pre-model approval is granted
• validates generated Markdown/MDX documentation patches
• opens a GitHub draft PR instead of writing to the default branch
• treats "no docs update needed" as a successful outcome

Supported documentation targets are intentionally narrow: README.md, docs/**/*.md, docs/**/*.mdx, and optionally CONTRIBUTING.md.

Quickstart

Create a starter config:

npx --no-install doksteward init

Then validate setup before allowing model calls or GitHub writes:

npx --no-install doksteward check
npx --no-install doksteward plan --dry-run
npx --no-install doksteward catch-up --since last-run --dry-run
npx --no-install doksteward catch-up --since <tag-or-sha> --dry-run
npx --no-install doksteward context --dry-run
npx --no-install doksteward run --dry-run

plan --dry-run, catch-up --dry-run, context --dry-run, and run --dry-run are inspectable local previews. They should not create branches, commits, or pull requests.

CLI Commands

Current command snapshot:

doksteward init
doksteward check
doksteward plan [--json]
doksteward plan --dry-run
doksteward catch-up --since <tag-or-sha> [--json]
doksteward catch-up --since last-run [--json]
doksteward catch-up --last <days> [--json]
doksteward catch-up --base <sha> --head <sha> [--json]
doksteward catch-up --since <tag-or-sha> --dry-run
doksteward catch-up --since last-run --dry-run
doksteward catch-up --last <days> --dry-run
doksteward catch-up --base <sha> --head <sha> --dry-run
doksteward context --dry-run
doksteward run --dry-run
doksteward run

Use check for config validation, plan for documentation impact planning, context --dry-run for inspectable scoped context previews, run --dry-run for patch previews, and run for the GitHub draft PR workflow.

Minimal doksteward.yml

Place doksteward.yml at the repository root. Keep raw credentials out of this file.

docs:
  targets:
    - README.md
    - docs/**/*.md
    - docs/**/*.mdx
    # Optional:
    # - CONTRIBUTING.md

ignore:
  paths:
    - node_modules/**
    - dist/**
    - build/**
    - coverage/**
    - package-lock.json
    - .git/**
    - .github/workflows/**
    - tests/fixtures/**

limits:
  maxChangedFiles: 20
  maxChangedLines: 300
  maxContextBytes: 120000

model:
  provider: anthropic
  model: claude-sonnet-4-6
  apiKeyEnv: ANTHROPIC_API_KEY

For approval-gated usage, add the GitHub workflow-input approval block and use the approved workflow shape in GitHub Actions setup:

approval:
  preModel:
    required: true
    github:
      signal: workflow-input
      inputName: dokstewardApproved

Local Validation

Use these commands while tuning config or reviewing a proposed CI setup:

npx --no-install doksteward check
npx --no-install doksteward plan --dry-run
npx --no-install doksteward catch-up --last 7 --dry-run
npx --no-install doksteward context --dry-run
npx --no-install doksteward run --dry-run

For local model-backed dry runs, set the configured provider environment variable before running commands that need the provider.

Do not commit provider keys or place raw secrets in doksteward.yml.

Catch-up Mode

Use catch-up mode to inspect a bounded historical range with the same docs targets, ignored paths, context limits, approval policy, model-provider boundaries, and patch safety rules used by the normal planning and run flows.

For normal catch-up, prefer selectors that resolve forward to the current HEAD:

doksteward catch-up --since last-run --dry-run
doksteward catch-up --since <tag-or-sha> --dry-run
doksteward catch-up --last <days> --dry-run

--since last-run resolves from the latest valid merged DokSteward commit marker found in reachable local Git history. The resolved catch-up base comes from that marker's DokSteward-Source-Head, and the catch-up head resolves to the current HEAD.

--since <tag-or-sha> resolves the selected baseline to the current HEAD. --last <days> resolves a recent time-window baseline to the current HEAD. --last must be a positive integer between 1 and 365.

Catch-up marker lookup is repo-local and commit-trailer-first. DokSteward treats marker data as untrusted input, validates it before use, and safe-stops clearly if the marker is missing, malformed, unavailable, or unusable in the current repository.

No-change runs are not tracked by --since last-run because they create no commits and therefore leave no durable commit marker.

For advanced or debug use, DokSteward also supports an exact historical slice:

doksteward catch-up --base <sha> --head <sha> --dry-run

--base <sha> --head <sha> is advanced exact-range mode. Prefer --since or --last for normal catch-up work because they resolve to the current HEAD. Exact base/head mode can inspect a historical slice and may warn when --head is not the current HEAD.

--json can be used where the current CLI JSON output is supported, for example:

doksteward catch-up --since last-run --json
doksteward catch-up --since <tag-or-sha> --json
doksteward catch-up --last <days> --json

If no last-run marker exists yet, fall back to an explicit historical selector such as:

doksteward catch-up --since <tag-or-sha> --dry-run
doksteward catch-up --last <days> --dry-run

In this release, catch-up mode is report-first. It can plan or dry-run bounded catch-up analysis, but it does not create files, branches, commits, or pull requests. Broad ranges may be safely batched or safely stopped with explicit limit reasons. When approval is configured, DokSteward still requires approval before model-provider calls.

GitHub Actions

The supported MVP CI path is GitHub Actions on the default branch after merges. The workflow checks out full git history, installs dependencies, runs npx --no-install doksteward run, and passes credentials through environment variables.

The GitHub Action wrapper is available as meisterware/[email protected]. Keep the Action tag aligned with the CLI package version used by your repository.

Required workflow permissions for draft PR creation:

permissions:
  contents: write
  pull-requests: write

Use repository secrets for model-provider credentials, for example ANTHROPIC_API_KEY. Use the default GITHUB_TOKEN with the minimum permissions above.

See GitHub Actions setup for the copy-pasteable workflow, approval-required setup, permissions, and troubleshooting notes.

Development from Source

From this repository checkout:

npm install
npm run build
npm run dev -- --version

Expected Outcomes

No docs update needed: DokSteward exits successfully, reports that no documentation update is needed, and does not create a branch or PR.

Approval missing: When pre-model approval is required and not granted, DokSteward safe-stops before model calls, branch creation, commits, or PR creation. Rerun with the configured approval input when you are ready to allow the model-provider call.

Draft PR generated: When a validated docs update is ready, DokSteward creates a non-default documentation branch, commits only allowed docs changes, and opens a GitHub draft PR for human review. It does not auto-merge and does not write directly to the default branch.

Run Markers

DokSteward-created documentation updates now include a small marker hierarchy for future history lookup.

Commit trailers are the primary durable marker. DokSteward-created docs commits append structured DokSteward-* trailers with a run id, CLI version, mode, range mode, source base and head SHAs, changed docs targets, and deterministic plan and change hashes.

Hidden PR metadata is the secondary provider-side marker. DokSteward-created draft PR bodies keep the existing human-readable sections and append a deterministic hidden <!-- doksteward ... --> block with the same safe metadata.

Branch names and optional PR labels are helper signals only. The stable branch naming convention keeps the doksteward/ prefix, with current docs-update branches shaped like doksteward/doc-update-<stable-id>-<12-hex-hash>. The prefix is a convention, not the durable source of truth. Future helper variants may use names such as doksteward/doc-catch-up-<short-head> or doksteward/doc-create-<short-head>.

.doksteward/state.json is future and optional only and is not used in this release. Hosted control-plane run history is also future only and is not implemented here.

Security and Privacy

DokSteward is CI-local and BYOM/API-key based. It is designed to avoid hosted repository ingestion by default and to keep generated documentation changes reviewable.

For context boundaries, credential handling, approval behavior, and GitHub write safety, see the security model. Report security issues privately according to SECURITY.md.

More Docs

• GitHub Actions setup - GitHub Actions setup, approval mode, and troubleshooting.
• Security model - security model, permissions, and privacy boundaries.
• Design partner readiness - concise pilot metrics and checklist.
• Milestones - roadmap context.
• Contributing - contribution guidance.

License

DokSteward CLI is released under the Apache License 2.0. See LICENSE for details.