# AI Capability Playbook Product Architecture

## Decision

The AI Capability Playbook is the active product surface for this workstream.

```text
AI Capability Playbook
  = governed living knowledge package
  + source/provenance discipline
  + artifact identity and export posture
  + AI-consumable context pack
  + future source-grounded interrogation layer
```

The product is not a standalone website shell, chatbot, dashboard, database, backend, model runtime, provider execution path, connector platform, desktop wrapper, or generic documentation pile. The durable product is the governed knowledge package and the evidence discipline around it.

SourceMesh and SourceMesh ArtifactPlane remain valuable reference repositories and primitive sources. They should not continue as independent UI-heavy product tracks for this workstream unless a later strategy issue explicitly reopens standalone development.

The repositories should not be merged wholesale at this stage. The current need is primitive extraction and convergence, not repository consolidation.

## Layer Model

| Layer | Role | Current posture |
|---|---|---|
| SourceMesh | Evidence, provenance, and source-pack primitive layer | Reference and primitive source, not active standalone product track for this workstream |
| SourceMesh ArtifactPlane | Artifact-compilation, export, and visual-learning primitive layer | Reference and primitive source, not active standalone product track for this workstream |
| AI Capability Playbook | Active governed knowledge package | Current product center |
| Context pack | AI-consumable grounded package | Static package surface for approved-source reasoning sessions |
| Source-grounded assistant | Future interrogation surface over approved package only | Keep open as later work after package boundary and primitive map are explicit |

## Product Boundary

The playbook should be developed as a governed living knowledge package with:

- canonical source and package identity
- source/provenance discipline
- claim and evidence posture
- artifact identity and export posture
- visible receipts and validation evidence
- static public and portable reading surfaces
- AI-consumable context pack
- future source-grounded interrogation over approved package content only

The playbook should not be developed as:

- a general chatbot
- a runtime agent platform
- a backend-first product
- a GUI polish program for SourceMesh or ArtifactPlane
- a provider/model execution surface
- a connector ingestion surface
- a merged monorepo for every related primitive
- a semantic enrichment runtime
- a durable memory system

## Source-Grounded Assistant Boundary

Issue #78 remains open and should follow this architecture decision. The assistant is a future interrogation surface over the approved package only.

Required assistant posture:

- answer from approved package sources only
- cite artifact, section, or source path where feasible
- state when an answer is not found in the package
- avoid external web retrieval unless a later private mode explicitly approves it
- avoid model-memory answers when the package is silent
- avoid implying policy approval, tool approval, data approval, production approval, or supplier approval

This architecture note does not implement assistant behavior.

## Backend And Graph Boundary

Issue #79 remains deferred. A living knowledge graph or relational backend may be evaluated later only after the static artifact identity, context pack, export posture, and source-boundary model prove which relationships cannot be handled with Markdown, HTML, manifests, JSONL, hashes, and receipts.

This architecture note does not create a database, graph, hosted service, private-data ingestion path, source-ingestion pipeline, or production backend.

## Reader Orientation Sequence

Issue #88 is the likely next product-facing work after this architecture slice unless later review changes sequencing. Reader orientation should help users enter the living knowledge package by job, task, source-boundary need, and artifact depth.

This architecture note does not change navigation, search, downloads, mobile layout, or public HTML behavior.

## DOCX Idempotence Sequence

Issue #151 is a valid P2 follow-up from the DOCX readability pass. It should not displace the architecture and reader-orientation sequence unless DOCX rebuild hygiene becomes a release blocker.

This architecture note does not alter DOCX generation.

## Paused Or Gated Lanes

The following lanes remain paused or gated for this workstream:

- SourceMesh GUI polish
- ArtifactPlane GUI polish
- desktop wrapper work
- Supabase/backend implementation
- connector ingestion
- model/provider execution
- embedding-provider upgrade work
- archive cleanup or mutation
- direct image generation
- semantic enrichment runtime
- RecallPlane durable memory

These lanes can be reopened only by a specific strategy issue with scope, acceptance criteria, validation posture, and package-boundary impact.

## Operating Implication

Future issues should prefer AICD-first changes that strengthen source identity, provenance, artifact identity, validation receipts, context-pack usability, reader orientation, and approved-package interrogation. Work that mainly improves standalone SourceMesh or ArtifactPlane UI, backend plumbing, provider execution, ingestion, or memory should remain out of sequence unless explicitly reopened.