feat: knowledge page seed taxonomy + capability degrade

[luxus]

Summary

Idempotent five-page knowledge taxonomy seed on coding project template apply and via hindsight_knowledge action seed_taxonomy. Degrades cleanly when knowledge-base APIs are unavailable.

Linked issue

• Closes feat: knowledge page seed taxonomy + capability degrade #559
• Epic epic: adopt coding-agents shortlist (bank strategies, KP seed, git seed, retain compact, eval) #557
• Stack: depends on feat: multi-strategy retain + knowledge entity_labels #564

Scope

• seedKnowledgePages with capability probe / knowledge_pages_unavailable
• Template apply seeds pages for pi-coding-project
• Tool action seed_taxonomy (dryRun default true)

Verification

• npm run check
• npm run check:coverage (source, tests, critical paths, or ci:coverage)
• npm run typecheck:tsc (source/critical paths or full CI)
• full matrix requested/passed (release PRs/release verification, manual dispatch, platform-sensitive changes, or ci:full)
• package verification requested/passed (release/package changes or ci:package)
• npm run pack:verify (release/package changes)
• npm run smoke:hindsight or configured Hindsight Integration pass (memory-path behavior changes or ci:live-smoke; document unavailable live proof)

Unit tests cover seed, skip-existing, and unavailable paths. Live seed requires server knowledge-base routes.

Release impact

• User-visible change

Template apply may create knowledge pages; new seed_taxonomy action.

Risk and rollback

• Risk: partial page creates if mid-seed network failure (errors reported per page).
• Rollback/revert path: revert PR; delete seeded pages via knowledge tool if needed.

Follow-ups

• feat: opt-in gitlog seed and sync readiness #566 git seed + sync status

Memory invariants

• Retain still stores raw rich content, not summaries.
• Recall Blocks remain ephemeral and are not retained back into Hindsight.
• Project Bank and User Bank isolation is preserved.
• Retain Queue behavior remains queue-first and retry-safe.
• Debug output and sidecars remain opt-in and redacted.
• Import behavior remains deterministic and idempotent when touched.

Guidance sync

• If this changes source-of-truth order, contributor workflow, verification expectations, memory policy, or definition of done, AGENTS.md and CONTRIBUTING.md were updated together.

Agent checklist

• I read and followed AGENTS.md and CONTRIBUTING.md.
• I linked the issue before implementation.
• I kept the diff focused on one vertical slice.
• Final branch contains only focused, reviewable commits.
• I did not bypass hooks or checks.
• I documented skipped checks with reasons.

Notes

Pages remain tool-driven; not auto-injected into context.

[Copilot]

🟡 Not ready to approve

It introduces a mutating helper that currently defaults to dryRun: false and documentation that doesn’t match the actual degradation reason returned when the client lacks the create-page wrapper.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

Adds an idempotent “knowledge page taxonomy seeding” path so coding banks can be initialized with a fixed five-page knowledge-page structure, while degrading cleanly when the Hindsight server/client lacks knowledge-page support.

Changes:

• Introduces seedKnowledgePages helper + tests to seed the fixed five-page taxonomy and gracefully handle missing capabilities.
• Adds hindsight_knowledge action seed_taxonomy and wires seeding into pi-coding-project template apply.
• Updates surface-reference docs (both repo docs and docs-site) and memory-behavior docs to describe the new action and behavior.

File summaries

File	Description
tests/knowledge-page-seed.test.ts	Adds unit tests covering seeding, dry-run behavior, idempotency (skip existing), and capability degradation.
extensions/operations/operation-catalog.ts	Exposes seed_taxonomy under hindsight_knowledge and treats it as mutating (dryRun defaults to true).
extensions/operations/memory-control-operations.ts	Implements the new seed_taxonomy action via seedKnowledgePages with project/user base tag defaults.
extensions/operations/memory-bank-template-operations.ts	Seeds taxonomy when applying pi-coding-project bank template (best-effort, respects dryRun).
extensions/banks/knowledge-page-seed.ts	New idempotent seeding helper with capability detection and best-effort creation loop.
docs/surface-reference.md	Documents seed_taxonomy in the CLI/tool surface reference.
docs/memory-behavior.md	Documents taxonomy seeding behavior and degradation.
docs-site/src/content/docs/reference/surface-reference.md	Mirrors seed_taxonomy docs for the published docs site.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 2
• Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.