refactor: de-brand terminology, add --dry-run and batch instructions

[digitarald]

Summary

De-brand user-facing terminology, add --dry-run to the instructions command, and introduce a batch instructions command for multi-root VS Code workspaces.

Terminology (35 files)

• "AI readiness" → "readiness" / "Readiness" across CLI, extension, docs, tests
• "Copilot instructions" → "instructions" in descriptions, UI labels, PR body text
• "file-based instructions" → "area instructions" in criteria messages and code comments
• De-branded PR body text: "GitHub Copilot" → "AI coding assistants"

New Features

--dry-run flag on instructions command

Preview what files would be generated without writing anything to disk. Works across all 4 code paths (nested root, flat root, nested area, flat area). With --json, emits a unified dryRunFiles array.

agentrc instructions --dry-run              # preview to stderr
agentrc instructions --dry-run --json       # JSON output with file paths + byte counts
agentrc instructions --dry-run --areas      # preview area instructions too

VS Code: Batch Instructions (Generate Instructions (All Roots))

New command for multi-root workspaces — generates instructions for every workspace root in one pass. Respects per-root agentrc.config.json strategy. Only visible when workspaceFolderCount > 1.

VS Code: pickWorkspacePath() migration

All extension commands now use pickWorkspacePath() which shows a QuickPick for multi-root workspaces (single-root returns immediately). Replaces getWorkspacePath() which always used the first folder.

TUI enhancements

• R key: Run readiness report with policy loading from agentrc.config.json
• N key (was F): Generate nested area instructions
• Removed dead readinessReport state

Extension improvements

• Config write-back in instructions command (ENOENT-safe catch)
• Policy loading in readiness command with policy count note
• Area QuickPick shows applyTo patterns in detail field
• Deprecation warnings for generate instructions/agents and --per-app

Fixes

• README maturity table was split in two — merged into one continuous table
• Model defaults updated to claude-sonnet-4.6
• Extension README: added judgeModel setting, fixed engine version to 1.109.0+
• Batch command: surfaces skip reasons ("file already exists" / symlink)
• Dry-run area paths: uses areaInstructionPath() for real file paths instead of synthetic area:name

Verification

• npm run typecheck — pass
• npm run lint — pass
• npm run test — 568/568 pass
• npm run build — pass
• Extension: node esbuild.mjs + npx tsc --noEmit — pass

[github-actions]

⚠️ AgentRC Eval

Could not read eval results: ENOENT: no such file or directory, open '.agentrc/evals/results.json'

[Copilot]

Pull request overview

Refactors user-facing terminology across the CLI, VS Code extension, docs, and tests (de-branding “AI readiness”/“Copilot instructions”), and adds new functionality around instruction generation (CLI --dry-run, VS Code multi-root batch generation, and multi-root workspace selection).

Changes:

• De-brands “AI readiness” → “readiness” and “Copilot instructions” → “instructions” across UI strings, docs, and tests.
• Adds CLI agentrc instructions --dry-run for previewing generated outputs (including JSON mode).
• Adds VS Code multi-root support via pickWorkspacePath() and a new “Generate Instructions (All Roots)” batch command.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
vscode-extension/src/extension.ts	Registers the new batch instructions command.
vscode-extension/src/commands/readiness.ts	Uses multi-root picker; loads policies from config; updates readiness UI text.
vscode-extension/src/commands/pr.ts	Uses multi-root picker for PR creation.
vscode-extension/src/commands/instructions.ts	Uses multi-root picker; adds config write-back; improves area QuickPick details.
vscode-extension/src/commands/init.ts	Uses multi-root picker; updates terminology in progress messaging.
vscode-extension/src/commands/generate.ts	Uses multi-root picker.
vscode-extension/src/commands/eval.ts	Uses multi-root picker.
vscode-extension/src/commands/batch.ts	Adds VS Code command to generate instructions across all workspace roots.
vscode-extension/src/commands/analyze.ts	Replaces single-root selection with multi-root QuickPick.
vscode-extension/resources/walkthrough/readiness.md	Updates walkthrough terminology (“AI-ready” → “Ready”).
vscode-extension/package.json	Renames command titles; contributes new batch instructions command + menus.
vscode-extension/README.md	Updates terminology; documents batch command; updates version/model defaults.
src/ui/tui.tsx	Adds “R” hotkey to run readiness report; renames key bindings; terminology updates.
src/ui/BatchReadinessTui.tsx	Renames “Batch AI Readiness Report” → “Batch Readiness Report”.
src/services/tests/visualReport.test.ts	Updates criterion title terminology.
src/services/tests/readiness.test.ts	Updates expectations/messages for “area instructions” terminology.
src/services/tests/readiness-output.test.ts	Updates markdown heading expectations.
src/services/tests/readiness-markdown.test.ts	Updates markdown formatting expectations and terminology.
src/commands/readiness.ts	Updates report title/headers terminology.
src/commands/instructions.ts	Adds --dry-run behavior and JSON output for previews; uses areaInstructionPath().
src/commands/init.ts	Updates “next steps” text to “readiness report”.
src/commands/generate.ts	Adds deprecation warnings for generate instructions/agents.
src/cli.ts	Updates command descriptions/flags; adds --dry-run to instructions.
packages/core/src/utils/pr.ts	De-brands PR body content (“Copilot” → “AI coding assistants” / “instructions”).
packages/core/src/services/visualReport.ts	Default report title + footer terminology updated.
packages/core/src/services/readiness/scoring.ts	Updates Level 2 description terminology.
packages/core/src/services/readiness/criteria.ts	Updates “custom instructions” criterion text and “area instructions” wording.
packages/core/src/services/readiness.ts	Mirrors readiness copy updates in the service implementation.
packages/core/src/services/instructions.ts	Updates area-instructions prompt wording (“file-based” → “area”).
packages/core/src/services/batch.ts	Updates commit/PR titles and readiness docstrings terminology.
examples/README.md	Updates example wording (“AI readiness” → “readiness”).
docs/product.md	Updates product copy terminology.
agentrc.eval.json	Updates eval prompts/expectations for de-branded terminology.
README.md	Updates CLI docs/terminology; documents --dry-run; updates examples/models.
.github/prompts/generate-improvements.prompt.md	Updates prompt wording to match new terminology.

Comments suppressed due to low confidence (3)

vscode-extension/src/commands/instructions.ts:133

• This command reads analysis from a global cache without checking that it corresponds to the currently picked workspacePath. In multi-root workspaces this can cause area selection + generation to run with the wrong analysis. Consider storing { repoPath, analysis } in the cache (or a per-workspace map) and re-analyzing when the cache doesn't match the selected root.
  src/commands/instructions.ts:117
• In --dry-run --json mode this records path as f.path (repo-relative) for nested outputs, but other dry-run branches record paths relative to process.cwd(). This makes the JSON payload inconsistent and hard to consume. Normalize all dry-run file paths to a single convention (e.g., repo-relative paths, or absolute paths) across all code paths.

              dryRunFiles.push(
                ...dryFiles.map((f) => ({
                  path: f.path,
                  bytes: Buffer.byteLength(f.content, "utf8")
                }))

src/commands/instructions.ts:176

• For flat root dry-run JSON, this pushes path: relPath where relPath is relative to process.cwd(). If --repo points elsewhere, consumers will get paths like ../some/repo/..., while nested dry-run returns repo-relative paths. Use a consistent base (prefer repo-relative paths like .github/... or absolute paths) for dry-run JSON entries.

          if (options.dryRun) {
            const relPath = path.relative(process.cwd(), outputPath);
            const byteCount = Buffer.byteLength(content, "utf8");
            if (shouldLog(options)) {
              progress.update(`[dry-run] Would write ${relPath} (${byteCount} bytes)`);

[digitarald]

Fixed in 4f56662. Added a guard: if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) — non-object JSON (arrays, primitives) is now treated as {} rather than erroneously mutated.

[digitarald]

Fixed in 4f56662. Warnings from nestedResult.warnings are now emitted in both dry-run and write modes.

[Copilot]

Pull request overview

This PR de-brands user-facing terminology (“AI readiness” → “readiness”, “Copilot instructions” → “instructions”), adds a --dry-run mode to the CLI instructions command, and introduces VS Code improvements for multi-root workspaces (QuickPick root selection + batch instructions generation).

Changes:

• Standardize “readiness” / “instructions” terminology across CLI, VS Code extension, docs, and tests.
• Add --dry-run to agentrc instructions with aggregated JSON output for previewing generated files.
• Improve VS Code multi-root UX via pickWorkspacePath() and a new “Generate Instructions (All Roots)” command.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
vscode-extension/src/extension.ts	Registers the new batch instructions command.
vscode-extension/src/commands/readiness.ts	Uses workspace picker; loads config policies and updates readiness report labeling.
vscode-extension/src/commands/pr.ts	Uses workspace picker for correct repo selection in multi-root.
vscode-extension/src/commands/instructions.ts	Uses workspace picker; writes back strategy selection; improves area QuickPick details.
vscode-extension/src/commands/init.ts	Uses workspace picker; updates progress text to “instructions”.
vscode-extension/src/commands/generate.ts	Uses workspace picker for multi-root correctness.
vscode-extension/src/commands/eval.ts	Uses workspace picker for multi-root correctness.
vscode-extension/src/commands/batch.ts	Adds “Generate Instructions (All Roots)” command implementation.
vscode-extension/src/commands/analyze.ts	Replaces getWorkspacePath() with multi-root pickWorkspacePath().
vscode-extension/resources/walkthrough/readiness.md	Updates walkthrough terminology.
vscode-extension/package.json	Renames command titles/strings and adds batch instructions command contribution/menu gating.
vscode-extension/README.md	Updates docs for new command titles, multi-root batch instructions, and settings defaults.
src/ui/tui.tsx	Adds readiness hotkey + de-branded strings; renames area instructions messaging to “nested”.
src/ui/BatchReadinessTui.tsx	Updates report title terminology.
src/services/tests/visualReport.test.ts	Updates expected readiness/instructions strings.
src/services/tests/readiness.test.ts	Updates tests to use “area instructions” terminology.
src/services/tests/readiness-output.test.ts	Updates markdown output expectations to “Readiness Report”.
src/services/tests/readiness-markdown.test.ts	Updates markdown formatting expectations and strings.
src/commands/readiness.ts	Updates CLI readiness output strings/headings.
src/commands/instructions.ts	Implements --dry-run behavior and aggregates preview output.
src/commands/init.ts	Updates “next steps” wording for readiness.
src/commands/generate.ts	Adds deprecation warnings for generate instructions/agents and --per-app.
src/cli.ts	Updates command descriptions/flags and adds --dry-run to instructions.
packages/core/src/utils/pr.ts	De-brands PR body text to “AI coding assistants” and updates headings.
packages/core/src/services/visualReport.ts	Updates default visual report title/footer terminology.
packages/core/src/services/readiness/scoring.ts	Updates maturity model description strings to “custom instructions”.
packages/core/src/services/readiness/criteria.ts	Updates criterion title/reasons and “area instructions” wording.
packages/core/src/services/readiness.ts	Mirrors readiness criteria/scoring terminology updates.
packages/core/src/services/instructions.ts	Updates area-instruction prompt wording (“area instruction” vs “file-based”).
packages/core/src/services/batch.ts	Updates commit/PR titles and readiness comment wording.
examples/README.md	Updates examples to “readiness”.
docs/product.md	Updates product doc maturity model terminology.
agentrc.eval.json	Updates eval prompt strings to “readiness” / “instructions”.
README.md	Updates top-level docs, adds --dry-run example, and refines concepts/terminology.
.github/workflows/eval.yml	Avoids posting PR comment when eval results file is missing; clarifies parse error text.
.github/prompts/generate-improvements.prompt.md	Updates prompt wording to match new terminology.

Comments suppressed due to low confidence (1)

src/commands/instructions.ts:357

• In the flat per-area --dry-run path, the reported byte count is based on body, but writeAreaInstruction() actually writes buildAreaInstructionContent(area, body) (YAML frontmatter + newlines). This makes the dry-run byte counts (and message) inaccurate; compute bytes from the full file content that would be written.

            if (options.dryRun) {
              if (shouldLog(options)) {
                progress.update(
                  `[dry-run] Would write area "${area.name}" (${Buffer.byteLength(body, "utf8")} bytes)`
                );
              }
              if (options.json) {
                dryRunFiles.push({
                  path: path.relative(repoPath, areaInstructionPath(repoPath, area)),
                  bytes: Buffer.byteLength(body, "utf8")
                });