# 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](install-cli.md) 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](#1-log-in-to-the-cli)). - 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](holocron-mcp.md). 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: ```text 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 ```powershell 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: ```text Validating API key (PROD)... ✓ Connection valid. Validated at 2026-10-01T15:15:12Z ``` If the test passes, skip to [step 2](#2-create-a-branch). 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: - **Record:** [Legends CLI Experience Api | API Keys](https://keepersecurity.com/vault/#detail/9RQ5ekissgGGk8PVWf1NMg) | 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`. !!! info "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: ```powershell legends login --env PROD ``` ```text Enter API key for PROD: ``` Omit `--env` to log in to the currently active environment. Then confirm it worked: ```powershell legends login test ``` !!! warning "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: ```powershell 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 ` 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`. ```powershell git clone cd git checkout -b docgen/initial ``` Name the branch something obvious — `docgen/initial` for a first run, `docgen/` for a targeted re-run. ## 3. Install the doc gen tooling From the root of the repository: ```powershell 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 ` | 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: ```text .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. ```powershell 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. === "VS Code / Visual Studio" 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//`. Kickoff prompt: ```text Generate documentation for this repository. Analyze the full repo, classify the documentation type, and run all phases through index generation and self-validation. ``` !!! tip "Agent chat commands" The agent responds to `status`, `config`, `set `, and `help` at any point during a run. === "Copilot CLI" 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: ```text Use the SAIF Doc Gen agent to generate documentation for this repository. Run all phases through index generation and self-validation. ``` === "GitHub Copilot App" 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): ```text 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): ```text Generate documentation for this repository. Run all phases through index generation and self-validation. ``` !!! note "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//` | `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//`, 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](reviewing-documentation.md) for the per-type checklist, and [Bugfix / quick fix](bugfix-quick-fix.md) 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). ```powershell 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](publishing-to-portal.md) to get the documentation onto this site.