Skip to content

Quick start

Your first documentation run, start to finish. By the end you will have a branch in a legacy repository containing generated documentation and an open pull request against its default branch.

Plan for a long run. Repository size barely matters — what drives the clock is the number of eligible libraries, because the agent generates a task set per library:

Eligible libraries Expect
1–10 2–4 hours
12–20 4–6 hours
More than 20 10–14 hours

Nearly all of that is the agent working unattended, so start a run when you can leave it alone. Ask the agent for status if you want to check progress.

Before you start

  • The legends CLI is installed and legends --version works.
  • You can read the Legends CLI Experience Api | API Keys Keeper record, or can request the key from the Architecture team (see step 1).
  • You can clone and push to the repository you want to document.
  • You have GitHub Copilot in whichever editor or client you plan to use.
  • Optional: set up Holocron MCP. Doc gen uses the Holocron tools when they are available and falls back to the legends CLI when they are not.

1. Log in to the CLI

During a run, the doc gen agents call the Legends CLI Experience API through commands such as legends oracle query and legends sqlserver query to pull stored procedure source. Those commands authenticate with an API key that the CLI stores per environment. Without one, they fail with:

Error: No API key stored for PROD. Run legends login --env PROD first.

You only need to log in once per machine and environment — the stored key is reused by every later run.

Check for an existing login

legends env          # shows the active environment (normally PROD)
legends login list   # environments that already have a stored key
legends login test   # validates the key for the active environment

A valid key looks like this:

Validating API key (PROD)...
✓ Connection valid. Validated at 2026-10-01T15:15:12Z

If the test passes, skip to step 2. If it reports that no key is stored, or validation fails, continue below.

Get the API key

The keys for every environment are stored in a single Keeper record:

Environment Keeper field
PROD Password
TEST TEST
QA QA
UAT UAT

The PROD key is the Password field, not a field named PROD. Doc gen runs use PROD unless you have switched environments with legends env --set.

No access to the Keeper record?

Request the key from the Architecture team by email, by posting in the General channel, or by opening a SNOW request.

Store the key

Run legends login in an interactive terminal and paste the key when prompted:

legends login --env PROD

Enter API key for PROD:

Omit --env to log in to the currently active environment. Then confirm it worked:

legends login test

Run legends login yourself, not through Copilot

The prompt needs an interactive console. Run from an agent or with redirected input, it fails with Failed to read input in non-interactive mode. Never paste the API key into a Copilot chat, a script, or a commit.

To log in to another environment, switch to it first, then log in and test:

legends env --set TEST
legends login
legends login test

To remove stored keys — for example after a key is rotated — use legends login clear --env <ENV> for one environment, or legends login clear for all of them (it asks for confirmation; add --all to skip the prompt). Then log in again.

2. Create a branch

Doc gen writes a lot of files. Never run it directly on main / master.

git clone <repo-url>
cd <repo>
git checkout -b docgen/initial

Name the branch something obvious — docgen/initial for a first run, docgen/<library-name> for a targeted re-run.

3. Install the doc gen tooling

From the root of the repository:

legends init

legends init copies the doc gen agents, prompts, skills, and templates into the repository. It hashes every file against what is already there, prints an Init Summary of Added / Updated / Removed / Unchanged, and asks before applying anything.

Option Effect
--dry-run Show what would change and exit. Run this first if you are unsure.
--force Apply without the confirmation prompt.
--path <dir> Target a directory other than the current one.
--clear-state Also wipe .saifdocgen/state/** from previous runs.

It manages exactly two roots, and prunes stale files inside them:

.github/
  agents/          saif-doc-gen, programmer-analyst, technical-architect,
                   technical-writer, documentation-reviewer
  prompts/         docgen-bugfix, docgen-quickfix
  skills/          legends-cli-search
.saifdocgen/
  config/          docgen-config.json + output contracts
  instructions/    analysis, global-docgen, diagram-lint, reviewer rules, ...
  prompts/         run-*/draft-*/review-* prompt files
  schemas/         document-metadata + retrieval-manifest JSON schemas
  skills/          per-topic SKILL.md files
  templates/       document templates per documentation type
  scripts/         deterministic validation scripts
  state/           run state (preserved across init unless --clear-state)

Commit and push the tooling before you start the agent. It gives you a clean point to diff the generated documentation against, and it is the state the Copilot App workflow below depends on.

git add .github .saifdocgen
git commit -m "chore: install SAIF doc gen tooling"
git push -u origin docgen/initial

4. Run doc gen with Copilot

The tooling installs a SAIF Doc Gen agent. How you invoke it depends on your Copilot client — follow the tab for the one you use.

  1. Open the repository folder.
  2. Open Copilot Chat and switch to Agent mode.
  3. Select SAIF Doc Gen using the agent dropdown, or type /agent in the chat input and pick it from the list.
  4. Send the kickoff prompt shown below.
  5. Leave the window open. The orchestrator dispatches sub-agents in batches and writes progress into .saifdocgen/state/runs/<run-id>/.

Kickoff prompt:

Generate documentation for this repository. Analyze the full repo, classify
the documentation type, and run all phases through index generation and
self-validation.

Agent chat commands

The agent responds to status, config, set <setting> <value>, and help at any point during a run.

  1. cd into the repository.
  2. Start Copilot CLI in the repo root so it picks up .github/agents.
  3. Type /agent and select SAIF Doc Gen from the list.
  4. Send the kickoff prompt shown below.

Because the CLI runs in your existing checkout, the branch you created in step 2 is already active — no extra setup.

Kickoff prompt:

Use the SAIF Doc Gen agent to generate documentation for this repository.
Run all phases through index generation and self-validation.

The Copilot App creates its own worktree and branch per session, so the branch and tooling install happen inside the session rather than ahead of it.

  1. Start a new session on the repository.
  2. Send the setup prompt shown below to prepare the branch and install the tooling.
  3. Fork the session. The agent picker does not pick up agents that were added on a branch after the session started, so the newly installed SAIF Doc Gen agent will not appear in the current session's dropdown. Forking creates a session whose workspace already contains .github/agents, so the picker is populated correctly.
  4. In the forked session, select SAIF Doc Gen using the agent dropdown, or type /agent and pick it from the list.
  5. Send the kickoff prompt shown below.

Setup prompt (step 2):

Create a branch named docgen/initial, run `legends init --force` in the
repository root to install the SAIF doc gen tooling, then commit and push
the .github and .saifdocgen folders.

Kickoff prompt (step 5):

Generate documentation for this repository. Run all phases through index
generation and self-validation.

Why the fork is needed

This is a UI limitation, not a tooling one. A session enumerates available agents when its workspace is created; a branch that gains .github/agents afterwards is not re-scanned. Forking after the push is the reliable workaround.

5. What the run produces

The agent classifies the repository into one documentation type — Framework, Component, Front End, Console App, Rest API, SOAP Service, Desktop App, or Windows Service — and that choice drives the output layout.

Every run writes:

Path Contents
docgen-manifest.md Run summary table, documentation type, and the one-sentence classification basis.
README.md Repository overview plus a table of generated libraries.
packages.md Published NuGet packages — only when package pipeline files exist.
docs/libraries/<slug>/ index, overview, architecture, dependencies, operations-processes, business-rules, and api/ pages.

Type-specific additions:

  • Front End also gets docs/index.md, docs/application/*.md, and docs/screens/ with one page per screen plus a screen index.
  • Console App also gets docs/applications/<app-slug>/, including the batch lifecycle and operational runbook pages.

Library folder names are slugs: dots become hyphens and everything is lowercased, so SAIF.Framework.Core becomes saif-framework-core.

6. Review

Do not merge the run unreviewed. The agent runs its own review and validation passes, but it is non-deterministic — a human still needs to check both content accuracy and formatting. See Reviewing documentation for the per-type checklist, and Bugfix / quick fix for how to repair individual documents without re-running everything.

7. Open a pull request

Commit the generated documentation and open a PR against the repository's default branch (master for most legacy repos, main for newer ones).

git add .
git commit -m "docs: generate SAIF documentation"
git push

Keep .saifdocgen/state/ out of the PR if your repository ignores it; otherwise leave it — it is the run history the tooling uses for incremental work.

Once the PR is merged, continue with Publishing to the portal to get the documentation onto this site.