docs(voyage): document v4.1 profiles + observability + doc-consistency-pinning

Step 22 of v4.1 — write top-level docs for the v4.1 feature surface.

Files updated:
  CLAUDE.md       — Commands tables: add --profile to all 6 modes
                    + new ## Profile system + ## Observability sections
  README.md       — per-command Modes tables: add --profile row
                    + new top-level ## Profile system + ## Observability
                    + cross-link from ## Cost profile
  CHANGELOG.md    — new "## v4.1.0 — 2026-05-09" entry per Keep-a-Changelog 1.1.0
                    (Added / Changed / Fixed / Notes)
  docs/profiles.md — NEW: 168-line decision tree, lookup precedence,
                    custom-profile authoring, drift detection,
                    cost-estimation table with disclaimer
  tests/lib/doc-consistency.test.mjs — extend with 5 new pinning tests:
                    CLAUDE.md --profile + phase_models canonical name,
                    README.md --profile coverage (≥ 6 mentions),
                    CHANGELOG.md v4.1.0 entry, docs/profiles.md substantive

ROADMAP.md is gitignored per marketplace policy (sesjonsfiler) — local
edit applied for v4.1 DONE marker, not committed.

Plan-critic Blocker 2 split is honored: Step 21 pinned commands-only;
Step 22 writes the docs and pins them. doc-consistency.test.mjs is
green AFTER Step 22 (would have failed if Step 22 ran in same wave).

Tests: 487 pass + 2 skipped (Docker not installed).

plugins/voyage/tests/lib/doc-consistency.test.mjs

@@ -301,6 +301,75 @@ test('at least one pipeline command-file references `phase_models` canonical nam
   );
 });
 
+// --- v4.1 Step 22 — post-write CLAUDE.md / README.md pinning ---
+//
+// Plan-critic Blocker 2 fix: Step 21 only pinned commands/*.md (which
+// are written in Step 7 / Wave 3). Step 22 writes the top-level docs
+// and extends pinning here so doc-consistency stays green AFTER Step 22.
+
+test('CLAUDE.md documents --profile flag', () => {
+  const md = read('CLAUDE.md');
+  assert.match(
+    md,
+    /--profile\b/,
+    'CLAUDE.md must document the --profile flag (v4.1 SC #20)',
+  );
+});
+
+test('CLAUDE.md uses canonical name `phase_models`', () => {
+  const md = read('CLAUDE.md');
+  assert.match(
+    md,
+    /phase_models/,
+    'CLAUDE.md must use canonical name "phase_models" (v4.1 SC #20)',
+  );
+  for (const bad of ['model_per_phase', 'phase_to_model', 'profile_phase_models']) {
+    assert.ok(
+      !md.includes(bad),
+      `CLAUDE.md must NOT use legacy alias "${bad}"`,
+    );
+  }
+});
+
+test('README.md documents --profile flag for all 6 commands', () => {
+  // SG1: README flag-table coverage is gating for SC #20. README is the
+  // primary discovery surface for new users.
+  const md = read('README.md');
+  // Top-level Profile system section is required so the flag is
+  // discoverable independent of per-command tables.
+  assert.match(md, /## Profile system/, 'README.md missing top-level "## Profile system" section');
+  // Every per-command Modes table must include --profile (count of
+  // --profile occurrences should be ≥ 6 — one per command + Profile
+  // system section).
+  const profileMentions = (md.match(/--profile\b/g) || []).length;
+  assert.ok(
+    profileMentions >= 6,
+    `README.md must mention --profile ≥ 6 times (one per command + section), got ${profileMentions}`,
+  );
+});
+
+test('CHANGELOG.md has v4.1.0 entry', () => {
+  const cl = read('CHANGELOG.md');
+  assert.match(
+    cl,
+    /## v4\.1\.0\b/,
+    'CHANGELOG.md must include "## v4.1.0" entry per Keep-a-Changelog 1.1.0',
+  );
+});
+
+test('docs/profiles.md exists and documents Custom.yaml authoring', () => {
+  const dp = read('docs/profiles.md');
+  assert.ok(dp.length > 1000, 'docs/profiles.md must be substantive (> 1000 chars)');
+  // Must document custom-profile authoring (Step 22 manifest must_contain
+  // pattern: "Custom.yaml" — case-insensitive match handled here as
+  // /[Cc]ustom[. ]/ to allow either "custom.yaml" or "Custom profile" prose).
+  assert.match(
+    dp,
+    /[Cc]ustom\.yaml|[Cc]ustom profile|<custom>\.yaml/,
+    'docs/profiles.md must document custom profile authoring',
+  );
+});
+
 test('commands/trekplan.md Phase 8 seals Opus-4.7 schema-drift defense', () => {
   const cmd = read('commands/trekplan.md');
   // Locate Phase 8 section