docs: rewrite README as landing page, add 8 user-facing doc pages

.github/workflows/daily-doc-updater.md

@@ -59,11 +59,14 @@ This is **@microsoft/agentrc** — a TypeScript CLI + VS Code extension for prim
 
 **Documentation locations:**
 
-- `README.md` — Main product overview, Quick Start, prerequisites, command reference
+- `README.md` — Main product overview, Quick Start, prerequisites
+- `docs/commands.md` — CLI command reference and options
 - `CONTRIBUTING.md` — Contribution workflow, code style, release process
 - `CHANGELOG.md` — Version history
-- `docs/product.md` — Product brief, maturity model, architecture decisions
-- `docs/plugins.md` — Plugin system documentation, architecture, plugin contract
+- `docs/getting-started.md` — Installation, prerequisites, first run walkthrough
+- `docs/concepts.md` — Maturity model, readiness pillars, instructions, evaluation
+- `docs/dev/product.md` — Product brief, maturity model, architecture decisions
+- `docs/dev/plugins.md` — Plugin system documentation, architecture, plugin contract
 - `.github/copilot-instructions.md` — Copilot coding instructions for the repo
 - `.github/instructions/*.instructions.md` — Scoped instructions for specific areas
 - `vscode-extension/README.md` — VS Code extension readme
@@ -123,7 +126,7 @@ Key conventions to follow:
 
 Review documentation files for:
 
-- New CLI commands or options not yet in README.md
+- New CLI commands or options not yet in `docs/commands.md`
 - New services or APIs not reflected in architecture docs
 - Changed behavior in existing commands
 - New VS Code extension features not in the extension README
@@ -140,8 +143,10 @@ find vscode-extension -name '*.md'
 For each missing or incomplete documentation:
 
 1. **Determine the correct file** based on the change type:
-   - CLI commands/options → `README.md`
-   - Architecture changes → `docs/product.md` or `docs/plugins.md`
+   - CLI commands/options → `docs/commands.md`
+   - Architecture changes → `docs/dev/product.md` or `docs/dev/plugins.md`
+   - User-facing concepts → `docs/concepts.md`
+   - Getting started content → `docs/getting-started.md`
    - Development workflow → `CONTRIBUTING.md`
    - Copilot coding context → `.github/copilot-instructions.md`
    - Area-specific instructions → `.github/instructions/*.instructions.md`

docs/at-scale.md

@@ -0,0 +1,89 @@
+# At Scale
+
+> [AgentRC](https://github.com/microsoft/agentrc) — prime your repositories for AI-assisted development.
+
+Everything that works on one repo also works on hundreds. AgentRC supports batch processing across GitHub organizations and Azure DevOps projects.
+
+## Batch processing
+
+Generate instructions and configs for multiple repos in one pass:
+
+```bash
+# Interactive TUI — select repos from your org
+npx github:microsoft/agentrc batch
+
+# Headless — GitHub repos
+npx github:microsoft/agentrc batch owner/repo1 owner/repo2
+
+# Headless — Azure DevOps repos
+npx github:microsoft/agentrc batch org/project/repo1 org/project/repo2 --provider azure
+```
+
+Repos can also be piped via stdin (one per line):
+
+```bash
+gh repo list my-org --json nameWithOwner -q '.[].nameWithOwner' \
+  | npx github:microsoft/agentrc batch
+```
+
+### Options
+
+| Flag              | Default             | Description          |
+| ----------------- | ------------------- | -------------------- |
+| `--output <path>` |                     | Write results JSON   |
+| `--provider <p>`  | `github`            | `github` or `azure`  |
+| `--model <name>`  | `claude-sonnet-4.6` | Model for generation |
+| `--branch <name>` |                     | Branch name for PRs  |
+
+## Consolidated readiness
+
+Get a single readiness report across all repos in your org:
+
+```bash
+npx github:microsoft/agentrc batch-readiness --output team.html
+```
+
+The HTML report shows per-repo scores, trends, and which repos need attention.
+
+| Flag                 | Default | Description                                  |
+| -------------------- | ------- | -------------------------------------------- |
+| `--output <path>`    |         | Write HTML report                            |
+| `--policy <sources>` |         | Comma-separated policy paths or npm packages |
+
+## Automated PRs
+
+Clone a repo, generate configs, and open a PR — all in one command:
+
+```bash
+# GitHub
+npx github:microsoft/agentrc pr owner/repo-name
+
+# Azure DevOps
+npx github:microsoft/agentrc pr org/project/repo --provider azure
+```
+
+| Flag              | Default                 | Description          |
+| ----------------- | ----------------------- | -------------------- |
+| `--branch <name>` | `agentrc/add-ai-config` | Branch name          |
+| `--provider <p>`  |                         | `github` or `azure`  |
+| `--model <name>`  | `claude-sonnet-4.6`     | Model for generation |
+
+## Authentication
+
+| Provider     | Required env var                                    |
+| ------------ | --------------------------------------------------- |
+| GitHub       | `GITHUB_TOKEN` or `GH_TOKEN`, or `gh` CLI logged in |
+| Azure DevOps | `AZURE_DEVOPS_PAT` or `AZDO_PAT`                    |
+
+## Repo format
+
+| Provider     | Format             | Example                    |
+| ------------ | ------------------ | -------------------------- |
+| GitHub       | `owner/repo`       | `microsoft/agentrc`        |
+| Azure DevOps | `org/project/repo` | `contoso/platform/backend` |
+
+## Next steps
+
+- [Policies](policies.md) — enforce org-specific standards across all repos
+- [CI Integration](ci-integration.md) — add readiness gates to every repo's pipeline
+- [Commands](commands.md) — full CLI reference for batch, batch-readiness, and pr

docs/ci-integration.md

@@ -0,0 +1,130 @@
+# CI Integration
+
+> [AgentRC](https://github.com/microsoft/agentrc) — prime your repositories for AI-assisted development.
+
+AgentRC commands return structured output and exit codes designed for CI pipelines.
+
+## Prerequisites
+
+- **Node.js 20+** on the runner
+- **Auth token** — GitHub: `GITHUB_TOKEN` or `GH_TOKEN`. Azure DevOps: `AZURE_DEVOPS_PAT` or `AZDO_PAT`.
+- **Copilot CLI** — required for `eval` (it calls the Copilot SDK). Not needed for `readiness`. See the [VS Code Copilot Chat extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) docs for installation.
+
+> `readiness` is a pure static analysis — it works anywhere Node runs. `eval` invokes AI models via the Copilot SDK, so the runner needs Copilot CLI installed and authenticated.
+
+## Readiness gate
+
+Fail if the repo drops below a maturity level:
+
+```bash
+agentrc readiness --fail-level 3 --json
+```
+
+Exits with code 1 if the readiness level is below 3. The `--json` flag outputs a machine-readable result to stdout.
+
+## Eval gate
+
+Fail if instruction quality drops below a pass rate:
+
+```bash
+agentrc eval agentrc.eval.json --fail-level 80 --json
+```
+
+Exits with code 1 if the pass rate is below 80%.
+
+## GitHub Actions
+
+```yaml
+name: AgentRC checks
+on: [pull_request]
+
+jobs:
+  readiness:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Check readiness
+        run: npx github:microsoft/agentrc readiness --fail-level 3 --json
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run eval
+        run: npx github:microsoft/agentrc eval --fail-level 80 --json
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # eval requires the GitHub Copilot CLI to be installed
+          # and authenticated on the runner (copilot → /login)
+```
+
+## Azure Pipelines
+
+```yaml
+trigger:
+  - main
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: "20.x"
+
+  - script: npx github:microsoft/agentrc readiness --fail-level 3 --json
+    displayName: Check readiness
+    env:
+      GITHUB_TOKEN: $(GITHUB_TOKEN) # for GitHub-hosted repos
+      # AZURE_DEVOPS_PAT: $(AZURE_DEVOPS_PAT)  # for Azure DevOps repos
+
+  - script: npx github:microsoft/agentrc eval --fail-level 80 --json
+    displayName: Run eval
+    env:
+      GITHUB_TOKEN: $(GITHUB_TOKEN)
+      # AZURE_DEVOPS_PAT: $(AZURE_DEVOPS_PAT)
+      # eval requires the GitHub Copilot CLI to be installed
+      # and authenticated on the runner (copilot → /login)
+```
+
+## Applying policies in CI
+
+Use a policy to enforce org-specific standards:
+
+```bash
+npx github:microsoft/agentrc readiness --policy ./policies/strict.json --fail-level 3 --json
+```
+
+## Any CI system
+
+The pattern works in any CI that has Node.js:
+
+```bash
+npx github:microsoft/agentrc readiness --fail-level 3 --json
+npx github:microsoft/agentrc eval --fail-level 80 --json
+```
+
+Both commands exit 0 on success and 1 when `--fail-level` is breached. Use `--json` to get structured output for downstream tooling.
+
+## Output format
+
+Both commands output a `CommandResult<T>` envelope when `--json` is set:
+
+```json
+{
+  "ok": true,
+  "status": "success",
+  "data": { ... }
+}
+```
+
+Status values: `"success"`, `"partial"`, `"noop"`, `"error"`. The process exit code is 0 for success and 1 when `--fail-level` is breached or a command error occurs.
+
+## Next steps
+
+- [At Scale](at-scale.md) — batch processing and automated PRs across orgs
+- [Policies](policies.md) — create org-specific readiness policies
+- [Commands](commands.md) — full flag reference for `readiness` and `eval`
+- [Concepts](concepts.md) — understand maturity levels and pass rates