# Product Architecture

This folder records product architecture decisions for the AI Capability Playbook workstream.

The active product surface is the governed living knowledge package: source-governed content, provenance, artifact identity, portable exports, context-pack generation, validation receipts, and future source-grounded interrogation over the approved package only.

These notes do not create runtime behavior, backend services, GUI work, provider execution, connector ingestion, repo migration, generated artifact redesign, policy approval, or production approval.

## Reader Orientation Bridge

The Start Here reader paths should make the governed package usable before any assistant exists. Human readers need stable entry points by job, task, source-boundary need, and artifact depth. Future assistant answers can later link back to those stable reader targets, but the human reading path must stand alone.

Recent product-architecture issues inform that orientation:

- #150 defines the AI Capability Playbook as the governed living knowledge package and keeps SourceMesh and ArtifactPlane as primitive sources, not active standalone product tracks.
- #153 defines future Find, Explain, and Assess behavior over the approved package only.
- #155 separates the human reader site, approved grounding corpus, and Microsoft-native interpretation surface.
- #156 keeps an external API reference implementation path portable while preserving the same source-grounded behavior contract.
- #158 makes model choice a routed architecture decision and preserves deterministic-first checks.
- #159 confirms that static pages can host reader targets and public corpus assets, but any real provider call requires a server-side boundary.
- #78 defines the non-runtime source-grounded assistant prototype contract, #79 remains deferred backend or graph evaluation, and #151 remains separate DOCX rebuild hygiene.
- #165 adds the first minimal external source-grounded chat proof as a public-corpus static shell plus a non-deployed server-side provider-boundary scaffold.

This orientation layer does not approve runtime assistant behavior, backend services, provider or model execution, Cloudflare deployment, Supabase integration, Copilot Studio configuration, connector ingestion, durable memory, private-data workflow, SourceMesh or ArtifactPlane repo changes, or enterprise workflow integration.

## Files

- [AI_CAPABILITY_PLAYBOOK_PRODUCT_ARCHITECTURE.md](AI_CAPABILITY_PLAYBOOK_PRODUCT_ARCHITECTURE.md): product boundary, layer model, sequencing, and non-goals for the AI Capability Playbook.
- [SOURCEMESH_ARTIFACTPLANE_PRIMITIVE_MAP.md](SOURCEMESH_ARTIFACTPLANE_PRIMITIVE_MAP.md): SourceMesh and SourceMesh ArtifactPlane primitive extraction map for the AICD-first workstream.
- [SOURCE_GROUNDED_SEMANTIC_EXPLAINER.md](SOURCE_GROUNDED_SEMANTIC_EXPLAINER.md): source-grounded Find, Explain, and Assess modes for the approved package.
- [PROPOSAL_ASSESSMENT_PATH.md](PROPOSAL_ASSESSMENT_PATH.md): proposal assessment dimensions, finding classes, and generated review-output boundaries.
- [SOURCE_GROUNDED_ASSISTANT_PROTOTYPE.md](SOURCE_GROUNDED_ASSISTANT_PROTOTYPE.md): non-runtime assistant prototype contract, corpus input contract, citation schema, refusal behavior, assessment classes, and static-safe boundaries.
- [MICROSOFT_NATIVE_INTERNAL_PILOT.md](MICROSOFT_NATIVE_INTERNAL_PILOT.md): Microsoft-first internal reader-site, grounding-corpus, and semantic-explainer pilot path.
- [WORKLOAD_MODEL_ROUTING_DISCIPLINE.md](WORKLOAD_MODEL_ROUTING_DISCIPLINE.md): workload classes, model tiers, cost-performance routing, and escalation discipline.
- [EXTERNAL_API_REFERENCE_IMPLEMENTATION.md](EXTERNAL_API_REFERENCE_IMPLEMENTATION.md): external API-backed reference path, adapter boundary, corpus limits, and portability to Microsoft-native deployment.
- [STATIC_SITE_CHAT_PROXY_REQUIREMENTS.md](STATIC_SITE_CHAT_PROXY_REQUIREMENTS.md): static-site chat-shell capabilities, server-side proxy requirements, candidate proof targets, and credential boundaries.