docs: full project analysis with recommendations and fixes

docs/architecture/components/inventory.md

@@ -6,6 +6,12 @@ This diagram shows the major internal components of the Inventory Application.
 
 This view breaks the Inventory Application into its main user interface, service, reporting, adjustment, and data access responsibilities. It provides the first detailed component-level view inside a Kell Creations application container.
 
+## Diagram Source
+
+The source for this diagram is maintained as architecture code in:
+
+`architecture/workspace/components-inventory.puml`
+
 ## Diagram
 
 ![Inventory Components](../../images/components-inventory.svg)

docs/architecture/containers/enterprise-data-architecture.md

@@ -14,7 +14,7 @@ The source for this diagram is maintained as architecture code in:
 
 ## Diagram
 
-![Enterprise Shared Services](../../images/containers-enterprise-services.svg)
+![Enterprise Data Architecture](../../images/enterprise-data-architecture.svg)
 
 ## Included Data Services and Stores
 

docs/architecture/containers/platform-containers.md

@@ -6,6 +6,12 @@ This diagram shows the major application and shared-service containers that make
 
 This view breaks the platform into its primary internal applications, shared services, and controlled content repositories. It is intended to show how the platform is logically organized before moving deeper into component-level and deployment-level views.
 
+## Diagram Source
+
+The source for this diagram is maintained as architecture code in:
+
+`architecture/workspace/containers-platform.puml`
+
 ## Diagram
 
 ![Platform Containers](../../images/containers-platform.svg)

docs/architecture/decisions/index.md

@@ -1,3 +1,84 @@
 # ADR Index
 
 Architecture Decision Records will be maintained here.
+
+## Current State
+
+No formal ADRs have been recorded yet. The following decisions have been identified through project analysis as candidates for retroactive ADR documentation.
+
+!!! info "Last analyzed: 2026-05-22"
+
+## Recommended ADRs
+
+The following significant architecture decisions are already in effect across the platform. Recording them as formal ADRs would establish an auditable decision history and provide context for future changes.
+
+### ADR-001 — Use C4 model with PlantUML as architecture-as-code standard
+
+- **Status:** Accepted (in practice)
+- **Context:** The platform needs a consistent architecture documentation approach that supports version control and CI/CD rendering
+- **Decision:** Use the C4 model (landscape, context, container, component) with PlantUML sources maintained in `architecture/workspace/`
+- **Consequences:** All 19 architecture diagrams follow this pattern; diagrams are rendered automatically via CI/CD; local preview requires PlantUML server access
+
+### ADR-002 — Use Flutter monorepo with shared packages for cross-platform applications
+
+- **Status:** Accepted (in practice)
+- **Context:** The platform needs to support both web and Android applications with shared business logic
+- **Decision:** Use a Flutter monorepo structure under `kell_creations_apps/` with shared packages (`core`, `design_system`, `feature_*`) and platform-specific app targets (`kell_web`, `kell_mobile`)
+- **Consequences:** Business logic is shared; domain/application/data/presentation layers are separated per package; each app target composes its own shell and routing
+
+### ADR-003 — Use `--dart-define` for runtime environment selection
+
+- **Status:** Accepted (in practice)
+- **Context:** The platform needs to switch between fake and real backends without code changes
+- **Decision:** Use `--dart-define` keys (`KC_ENV`, `KC_WC_SITE_URL`, etc.) to select runtime environment at build time
+- **Consequences:** No settings UI needed; credentials are never hardcoded; `KcBootstrap` handles fallback to fake mode when WP credentials are missing
+
+### ADR-004 — Use MkDocs Material with Forgejo CI/CD for documentation publishing
+
+- **Status:** Accepted (in practice)
+- **Context:** The platform needs a docs-as-code publishing pipeline
+- **Decision:** Use MkDocs Material as the documentation framework, published via Forgejo Actions with dedicated runners on the Ubuntu documentation host
+- **Consequences:** Documentation is version-controlled; publish and validate workflows are separated by branch; the published site at `docs.kellsupport.com` is automatically updated on `main` branch pushes
+
+### ADR-005 — Use abstract service composition pattern in `core` for cross-platform app shells
+
+- **Status:** Accepted (in practice)
+- **Context:** `kell_web` and `kell_mobile` need to share composition logic without circular dependencies
+- **Decision:** Extract abstract composition types (`KcAppConfig`, `KcAppServices`, `KcServiceFactory`, `KcBootstrap`, `KcAppScope`) into the `core` package; each app target provides concrete implementations
+- **Consequences:** Composition contract is enforced; circular dependencies avoided; `kell_web` retains backward-compatible typedefs; documented in `kell_creations_apps/docs/composition-strategy.md`
+
+### ADR-006 — Maintain policy repository with controlled lifecycle and YAML front matter metadata
+
+- **Status:** Accepted (in practice)
+- **Context:** The business needs formal governance for policies, procedures, standards, and exceptions
+- **Decision:** Use a Git-based policy repository with lifecycle directories (`drafts/`, `review/`, `active/`, `retired/`), YAML front matter metadata, CSV registers, and evidence retention
+- **Consequences:** All controlled documents follow a defined lifecycle; metadata requirements prevent informal policy creation; registers and evidence support audit readiness
+
+### ADR-007 — Use Forgejo Actions with dedicated runners for CI/CD pipelines
+
+- **Status:** Accepted (in practice)
+- **Context:** The platform needs automated validation and publishing for both documentation and Flutter applications
+- **Decision:** Use Forgejo Actions with two runner types: a Docker runner for containerized workloads and a host runner for direct filesystem access (publishing, rsync)
+- **Consequences:** Four workflows operational (`publish-docs`, `validate-docs`, `flutter-analyze`, `flutter-test`); runner tokens must be managed securely; host runner limited to narrowly defined workflows
+
+## ADR Template
+
+When recording new ADRs, use the following structure:
+
+```markdown
+### ADR-NNN — Title
+
+- **Status:** Proposed | Accepted | Deprecated | Superseded
+- **Context:** What is the issue that we're seeing that motivates this decision?
+- **Decision:** What is the change that we're proposing and/or doing?
+- **Consequences:** What becomes easier or more difficult to do because of this change?
+```
+
+## Maintenance
+
+New ADRs should be added when:
+
+- A significant technology, framework, or tool choice is made
+- A structural or organizational pattern is established or changed
+- A decision constrains future development options
+- A previous ADR is superseded or deprecated

docs/architecture/index.md

@@ -1,3 +1,120 @@
 # Architecture Overview
 
 This section documents the Kell Creations platform using C4 modeling, PlantUML, and supporting technical documentation.
+
+## Architecture Model
+
+The platform architecture follows the C4 model with five distinct view types:
+
+| Level | View             | Purpose                                                         |
+| ----- | ---------------- | --------------------------------------------------------------- |
+| 1     | System Landscape | Highest-level view of the platform and its external environment |
+| 2     | System Context   | Platform boundary with users and external systems               |
+| 3     | Container        | Major application and shared-service containers                 |
+| 4     | Component        | Internal structure of each application container                |
+| —     | Dynamic          | Cross-application workflow and sequence diagrams                |
+| —     | Deployment       | Runtime topology and infrastructure                             |
+
+## Architecture Artifacts
+
+All architecture diagrams are maintained as code using PlantUML (C4-PlantUML) in `architecture/workspace/`. Documentation pages in `docs/architecture/` provide narrative context, included elements, and notes for each diagram.
+
+### Current inventory
+
+| Category         | Count  | Files                                                                                                |
+| ---------------- | ------ | ---------------------------------------------------------------------------------------------------- |
+| System Landscape | 1      | `system-landscape.puml`                                                                              |
+| System Context   | 1      | `context-kellcreations-platform.puml`                                                                |
+| Container views  | 6      | Platform containers, enterprise services, data, identity & access, integration, audit                |
+| Component views  | 5      | Inventory, MRP, WordPress management, social media, financial analysis                               |
+| Dynamic views    | 5      | Order-to-fulfillment, product publishing, social campaign, inventory-to-production, policy lifecycle |
+| Deployment views | 1      | Production deployment                                                                                |
+| **Total**        | **19** | All maintained as PlantUML in `architecture/workspace/`                                              |
+
+## Analysis Findings
+
+!!! info "Last analyzed: 2026-05-22"
+
+The following findings were identified through a full review of the architecture documentation, PlantUML sources, and cross-referencing with the application codebase.
+
+### Confirmed strengths
+
+1. **Complete C4 coverage** — All four C4 levels are documented with consistent structure across views
+2. **Architecture as code** — All 19 diagrams are maintained as PlantUML source, rendered via CI/CD pipeline
+3. **Traceability index** — A comprehensive cross-reference maps business domains to architecture artifacts, workflows, and governance documents
+4. **Enterprise service backbone** — Shared services (authentication, data, integration, audit, notifications) are architecturally defined and consistently referenced across all application component views
+5. **CI/CD integration** — PlantUML rendering is integrated into the publish and validate workflows with automatic SVG generation
+
+### Issues identified
+
+#### 1. Enterprise Data Architecture — wrong diagram reference
+
+**Severity:** High
+
+The file `docs/architecture/containers/enterprise-data-architecture.md` references the wrong SVG image:
+
+```markdown
+![Enterprise Shared Services](../../images/containers-enterprise-services.svg)
+```
+
+This should reference `enterprise-data-architecture.svg` instead. The corresponding PlantUML source file exists (`enterprise-data-architecture.puml`) but the documentation page displays the enterprise services diagram instead of the data architecture diagram.
+
+**Recommendation:** Fix the image reference to point to the correct SVG.
+
+#### 2. Missing diagram source references
+
+**Severity:** Low
+
+The following documentation pages do not include a "Diagram Source" section pointing to their PlantUML file:
+
+- `docs/architecture/system-landscape.md` — missing reference to `architecture/workspace/system-landscape.puml`
+- `docs/architecture/containers/platform-containers.md` — missing reference to `architecture/workspace/containers-platform.puml`
+- `docs/architecture/components/inventory.md` — missing reference to `architecture/workspace/components-inventory.puml`
+
+All other architecture documentation pages include this reference consistently. These three should be updated for consistency.
+
+#### 3. ADR index is empty
+
+**Severity:** Medium
+
+The Architecture Decision Record (ADR) index exists at `docs/architecture/decisions/index.md` but contains no entries. Several significant architectural decisions have already been made and should be captured:
+
+**Recommended initial ADRs:**
+
+| ADR     | Decision                                                                            |
+| ------- | ----------------------------------------------------------------------------------- |
+| ADR-001 | Use C4 model with PlantUML as architecture-as-code standard                         |
+| ADR-002 | Use Flutter monorepo with shared packages for cross-platform applications           |
+| ADR-003 | Use `--dart-define` for runtime environment selection (fake vs. real backends)      |
+| ADR-004 | Use MkDocs Material with Forgejo CI/CD for documentation publishing                 |
+| ADR-005 | Use abstract service composition pattern in `core` for cross-platform app shells    |
+| ADR-006 | Maintain policy repository with controlled lifecycle and YAML front matter metadata |
+| ADR-007 | Use Forgejo Actions with dedicated runners for CI/CD pipelines                      |
+
+#### 4. Architecture-to-implementation gap
+
+**Severity:** Medium
+
+The architecture documentation describes rich capabilities across all five business domains, but actual implementation maturity varies significantly. Only `feature_wordpress` has substantial implementation. This creates a risk that architecture documentation may be perceived as describing current state rather than target state.
+
+**Recommendation:** Add a clear "implementation status" or "maturity" indicator to each component view documentation page, or maintain a single cross-reference (already partially addressed by the feature maturity matrix in the master development brief).
+
+#### 5. No architecture for the documentation platform itself
+
+**Severity:** Low
+
+The deployment view covers the documentation publishing infrastructure, but there is no component-level architecture for the documentation platform itself (MkDocs, PlantUML server, Forgejo runners, published site). Given the CI/CD complexity already documented in the operations section, a lightweight component view could help operational clarity.
+
+#### 6. Images directory not committed to Git
+
+**Severity:** Informational
+
+The `docs/images/` directory does not exist in the repository. SVG images are generated at CI/CD time by the publish and validate workflows. This is by design — the workflows create the directory, render PlantUML to SVG, and copy files before the MkDocs build. This is architecturally sound but means local MkDocs builds without running the PlantUML render step will have broken image references.
+
+**Recommendation:** Document this behavior in the architecture workflow documentation so new contributors understand that `docs/images/` is a build artifact, not a committed directory.
+
+## Related Pages
+
+- [Architecture Principles](principles.md)
+- [Traceability Index](traceability-index.md)
+- [ADR Index](decisions/index.md)

docs/architecture/system-landscape.md

@@ -8,6 +8,12 @@ It identifies the primary business users, the central Kell Creations platform, a
 
 This view is intended to provide a management-level understanding of the platform ecosystem. It is the starting point for more detailed context, container, component, deployment, and workflow diagrams.
 
+## Diagram Source
+
+The source for this diagram is maintained as architecture code in:
+
+`architecture/workspace/system-landscape.puml`
+
 ## Diagram
 
 ![System Landscape](../images/system-landscape.svg)

docs/architecture/traceability-index.md

@@ -26,7 +26,7 @@ Use this page to answer questions such as:
 ## 1. Enterprise Architecture Traceability
 
 | Enterprise View                                     | File                                                                                | Supports Domains                                                               |
-|---|---|---|
+| --------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
 | System Landscape                                    | `docs/architecture/system-landscape.md`                                             | All domains                                                                    |
 | Platform Context                                    | `docs/architecture/context/platform.md`                                             | All domains                                                                    |
 | Platform Containers                                 | `docs/architecture/containers/platform-containers.md`                               | All domains                                                                    |
@@ -42,7 +42,7 @@ Use this page to answer questions such as:
 ## 2. Application Component Traceability
 
 | Application Domain        | Component View                       | File                                                      | Related Enterprise Views                                     |
-|---|---|---|---|
+| ------------------------- | ------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------ |
 | Inventory                 | Inventory Components                 | `docs/architecture/components/inventory.md`               | Shared Services, Data, Identity & Access, Audit, Integration |
 | Craft Manufacturing / MRP | Craft Manufacturing / MRP Components | `docs/architecture/components/mrp.md`                     | Shared Services, Data, Identity & Access, Audit, Integration |
 | WordPress Management      | WordPress Management Components      | `docs/architecture/components/wordpress-management.md`    | Shared Services, Data, Identity & Access, Integration, Audit |
@@ -54,7 +54,7 @@ Use this page to answer questions such as:
 ## 3. Dynamic Workflow Traceability
 
 | Workflow                                | File                                                      | Primary Domains                               | Related Component Views                                |
-|---|---|---|---|
+| --------------------------------------- | --------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------ |
 | Order to Fulfillment                    | `docs/architecture/dynamic/order-to-fulfillment.md`       | WordPress, Inventory, MRP, Financial Analysis | Inventory, MRP, WordPress, Financial Analysis          |
 | Product Publishing Workflow             | `docs/architecture/dynamic/product-publishing.md`         | WordPress Management, Shared Data             | WordPress Management                                   |
 | Social Campaign Publishing Workflow     | `docs/architecture/dynamic/social-campaign-publishing.md` | Social Media Management, Integration          | Social Media Management                                |
@@ -66,7 +66,7 @@ Use this page to answer questions such as:
 ## 4. Governance Document Traceability
 
 | Governance Document                    | File                                                                                | Governs Domains               | Related Workflows / Views                                                |
-|---|---|---|---|
+| -------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------ |
 | Document Control Policy                | `docs/policies/governance/KC-POL-GOV-001-document-control-policy.md`                | Governance, Policy Repository | Policy Approval and Retirement Workflow, Audit & Compliance Architecture |
 | Policy Review and Retirement Procedure | `docs/policies/governance/KC-PRO-GOV-001-policy-review-and-retirement-procedure.md` | Governance, Policy Repository | Policy Approval and Retirement Workflow, Audit & Compliance Architecture |
 
@@ -75,6 +75,7 @@ Use this page to answer questions such as:
 ## 5. Domain-to-Artifact Mapping
 
 ### Inventory
+
 - Component View:
   - `docs/architecture/components/inventory.md`
 - Dynamic Workflows:
@@ -88,6 +89,7 @@ Use this page to answer questions such as:
   - Integration & Orchestration
 
 ### Craft Manufacturing / MRP
+
 - Component View:
   - `docs/architecture/components/mrp.md`
 - Dynamic Workflows:
@@ -101,6 +103,7 @@ Use this page to answer questions such as:
   - Integration & Orchestration
 
 ### WordPress Management
+
 - Component View:
   - `docs/architecture/components/wordpress-management.md`
 - Dynamic Workflows:
@@ -115,6 +118,7 @@ Use this page to answer questions such as:
   - Deployment
 
 ### Social Media Management
+
 - Component View:
   - `docs/architecture/components/social-media-management.md`
 - Dynamic Workflows:
@@ -127,6 +131,7 @@ Use this page to answer questions such as:
   - Audit & Compliance
 
 ### Financial Analysis
+
 - Component View:
   - `docs/architecture/components/financial-analysis.md`
 - Dynamic Workflows:
@@ -138,6 +143,7 @@ Use this page to answer questions such as:
   - Audit & Compliance
 
 ### Governance / Policy Repository
+
 - Governance Documents:
   - `docs/policies/governance/KC-POL-GOV-001-document-control-policy.md`
   - `docs/policies/governance/KC-PRO-GOV-001-policy-review-and-retirement-procedure.md`
@@ -155,20 +161,28 @@ Use this page to answer questions such as:
 
 The following areas are strong candidates for future documentation:
 
+!!! info "Last analyzed: 2026-05-22"
+
 ### Additional component views
+
 - Policy Repository internal components
 - Notification Service internal components
 - API Orchestrator internal components
 - Shared Data Repository internal components
+- Documentation Platform internal components (MkDocs, PlantUML server, Forgejo runners)
 
 ### Additional dynamic workflows
+
 - Financial close / reporting workflow
 - Website change management workflow
 - Exception handling workflow
 - Marketing campaign analytics workflow
 - Product image / media synchronization workflow
+- Local development setup workflow
+- Incident response workflow
 
 ### Additional governance documents
+
 - Access Control Policy
 - Social Media Publishing Standard
 - Product Publishing Procedure
@@ -178,6 +192,29 @@ The following areas are strong candidates for future documentation:
 - Website Change Management Procedure
 - Exception Management Standard
 
+### Architecture decisions
+
+- No formal ADRs exist; 7 candidate ADRs identified — see [ADR Index](decisions/index.md)
+
+### Standards documents
+
+- No formal standards documents exist; 10 candidate standards identified — see [Standards Overview](../standards/index.md)
+
+### Operational procedures
+
+- No operational runbooks exist; 5 candidate procedures identified — see [Operations Overview](../operations/index.md)
+
+### Integration documentation
+
+- Only WooCommerce integration is implemented; 5 additional integrations architecturally defined — see [Integrations Overview](../integrations/index.md)
+
+### Documentation quality issues
+
+- Enterprise Data Architecture page references wrong SVG diagram — **fixed 2026-05-22**
+- Three architecture pages were missing "Diagram Source" references — **fixed 2026-05-22**
+- Policy register CSVs are empty (header only) despite 2 active governance documents
+- `feature_orders` package is missing standard scaffolding files (`.gitignore`, `.metadata`, `CHANGELOG.md`, `LICENSE`, `README.md`) present in all other packages
+
 ---
 
 ## 7. Maintenance Rules

docs/brand/index.md

@@ -1,3 +1,73 @@
 # Brand Standards
 
 This section maps the Kell Creations brand guide into reusable documentation and design standards.
+
+## Current State
+
+No formal brand documentation has been published yet. Brand-related design elements exist in the `design_system` Flutter package but have not been documented as brand standards.
+
+## Existing Brand Elements
+
+### Design system implementation
+
+The `design_system` package (`kell_creations_apps/packages/design_system/`) contains the following brand-relevant components:
+
+| Element        | Implementation  | Notes                                                   |
+| -------------- | --------------- | ------------------------------------------------------- |
+| Color palette  | `KcColors`      | Brand colors defined as Flutter constants               |
+| Spacing system | `KcSpacing`     | Consistent spacing scale                                |
+| Typography     | `KcTypography`  | Full Material 3 text style hierarchy                    |
+| Theme          | `KcTheme`       | Composed theme applying colors, typography, and spacing |
+| Breakpoints    | `KcBreakpoints` | Responsive layout breakpoints for web and mobile        |
+
+### Reusable brand widgets
+
+| Widget            | Purpose                              |
+| ----------------- | ------------------------------------ |
+| `KcCard`          | Standard content card                |
+| `KcStatusChip`    | Status indicator chip                |
+| `KcSectionHeader` | Section heading with optional action |
+| `KcSummaryCard`   | Dashboard summary card               |
+| `KcEmptyState`    | Empty/placeholder state display      |
+| `KcLoadingState`  | Loading indicator                    |
+| `KcErrorState`    | Error display with optional retry    |
+
+## Recommendations
+
+!!! info "Last analyzed: 2026-05-22"
+
+### 1. Document color palette and usage guidelines
+
+**Priority:** Medium
+
+The `KcColors` class defines the color palette, but there is no documentation specifying:
+
+- Primary, secondary, and accent color usage
+- Accessibility contrast requirements
+- Color usage in different contexts (backgrounds, text, borders, status indicators)
+
+### 2. Document typography scale and usage
+
+**Priority:** Medium
+
+`KcTypography` defines the full type hierarchy but lacks documentation on:
+
+- When to use each text style (headings, body, captions, labels)
+- Font family and weight guidelines
+- Line height and letter spacing rationale
+
+### 3. Create a visual brand style guide
+
+**Priority:** Low
+
+A visual reference showing the brand elements in use would help maintain consistency across web and mobile platforms. This could be a dedicated MkDocs page with color swatches, typography samples, and widget examples.
+
+### 4. Document logo and asset guidelines
+
+**Priority:** Low
+
+No logo or visual asset documentation exists. If brand logos, icons, or imagery guidelines exist, they should be documented here.
+
+## Relationship to Design System
+
+The `design_system` package is the programmatic implementation of brand standards. Changes to brand standards should be reflected in the design system, and vice versa. The design system has full test coverage (41 tests, 100% line coverage as of 2026-05-22).

docs/development/master_development_brief.md

@@ -502,6 +502,46 @@ The architecture documentation describes rich capabilities across all domains (I
 
 **Recommendation:** Add a **feature maturity matrix** to this brief or a companion document that maps architecture aspirations to actual implementation status per feature package. This would make prioritization conversations clearer.
 
+### 11. Policy register CSVs are empty
+
+The policy repository has 2 active governance documents (`KC-POL-GOV-001`, `KC-PRO-GOV-001`), but the register CSVs (`policy-register.csv`, `document-control-log.csv`, `review-calendar.csv`) contain headers only with no data rows. This means the controlled document lifecycle described in the Document Control Policy is not being followed for the governance documents themselves.
+
+**Recommendation:** Populate the register CSVs with entries for the 2 active governance documents. This should be done before any additional policies are created.
+
+### 12. `feature_orders` package missing standard scaffolding
+
+The `feature_orders` package is missing standard scaffolding files (`.gitignore`, `.metadata`, `CHANGELOG.md`, `LICENSE`, `README.md`) that are present in all other packages. This creates inconsistency across the monorepo.
+
+**Recommendation:** Add the missing files to `feature_orders` to match the structure of other packages. This is a low-effort, high-consistency improvement.
+
+### 13. Architecture documentation shows wrong diagram
+
+The Enterprise Data Architecture documentation page (`docs/architecture/containers/enterprise-data-architecture.md`) was referencing the wrong SVG image (showing the enterprise services diagram instead of the data architecture diagram).
+
+**Resolution:** ✅ Fixed 2026-05-22 during full project analysis. Image reference corrected to `enterprise-data-architecture.svg`.
+
+### 14. Missing diagram source references in architecture docs
+
+Three architecture documentation pages were missing the standard "Diagram Source" section pointing to their PlantUML file:
+
+- `docs/architecture/system-landscape.md`
+- `docs/architecture/containers/platform-containers.md`
+- `docs/architecture/components/inventory.md`
+
+**Resolution:** ✅ Fixed 2026-05-22 during full project analysis. Diagram source references added for consistency.
+
+### 15. Empty documentation sections need initial content
+
+The Standards, Integrations, and Brand documentation sections had placeholder-only index pages with no substantive content.
+
+**Resolution:** ✅ Populated 2026-05-22 during full project analysis. Each section now includes current state assessment, recommendations, and actionable next steps.
+
+### 16. ADR index needs retroactive entries
+
+The Architecture Decision Record (ADR) index exists but contained no entries. Seven significant architecture decisions are already in effect across the platform.
+
+**Resolution:** ✅ Populated 2026-05-22 during full project analysis. Seven candidate ADRs documented with status, context, decision, and consequences.
+
 ---
 
 ## Required development workflow for every slice

docs/index.md

@@ -1,3 +1,49 @@
 # Kell Creations Platform
 
 This site is the central documentation portal for Kell Creations applications, services, architecture, policies, and operating processes.
+
+## Platform Health Summary
+
+This section provides an at-a-glance assessment of the platform's documentation, architecture, application, and governance maturity. It is maintained through periodic full-project analysis.
+
+!!! info "Last reviewed: 2026-05-22"
+
+### Documentation maturity
+
+| Area                    | Status              | Notes                                                               |
+| ----------------------- | ------------------- | ------------------------------------------------------------------- |
+| Architecture (C4 model) | ✅ Comprehensive    | All C4 levels documented with PlantUML sources                      |
+| Architecture decisions  | ⚠️ Empty            | ADR index exists but no decisions recorded                          |
+| Governance policies     | ✅ Foundation set   | 2 active governance documents, templates complete                   |
+| Operations runbooks     | ⚠️ Minimal          | CI/CD and architecture workflow documented; no operational runbooks |
+| Standards               | ⚠️ Placeholder only | Index page exists with no content                                   |
+| Integrations            | ⚠️ Placeholder only | Index page exists with no content                                   |
+| Brand                   | ⚠️ Placeholder only | Index page exists with no content                                   |
+| Development planning    | ✅ Comprehensive    | Master brief, tracker, composition strategy documented              |
+
+### Application maturity
+
+| Package             | Implementation   | Tests   | Production readiness |
+| ------------------- | ---------------- | ------- | -------------------- |
+| `feature_wordpress` | ✅ Complete      | 294     | Production-ready     |
+| `feature_inventory` | ✅ Fake-only MVP | Minimal | Fake-only            |
+| `feature_orders`    | ✅ Fake-only MVP | Some    | Fake-only            |
+| `feature_policy`    | ✅ Fake-only MVP | Minimal | Fake-only            |
+| `feature_finance`   | ❌ Stub          | None    | Scaffolded only      |
+| `feature_mrp`       | ❌ Stub          | None    | Scaffolded only      |
+| `feature_social`    | ❌ Stub          | None    | Scaffolded only      |
+| `auth`              | ❌ Stub          | None    | Scaffolded only      |
+| `data`              | ❌ Stub          | None    | Scaffolded only      |
+| `integrations`      | ❌ Stub          | None    | Scaffolded only      |
+
+### Key recommendations
+
+The following high-priority recommendations were identified through full-project analysis. Detailed findings are documented in [Architecture Overview](architecture/index.md), [Standards Overview](standards/index.md), [Operations Overview](operations/index.md), and the [Master Development Brief](development/master_development_brief.md).
+
+1. **Fix broken diagram image reference** — The Enterprise Data Architecture page references the wrong SVG file
+2. **Populate empty documentation sections** — Standards, Integrations, and Brand sections need initial content
+3. **Record architecture decisions** — Start capturing ADRs for key decisions already made
+4. **Populate policy registers** — Active governance documents are not reflected in register CSVs
+5. **Expand CI/CD validation** — Add Markdown linting, link checking, and PlantUML validation
+6. **Add missing diagram source references** — Some architecture docs are missing PlantUML source paths
+7. **Plan infrastructure package activation** — `auth`, `data`, and `integrations` packages need activation roadmaps

docs/integrations/index.md

@@ -1,3 +1,71 @@
 # Integrations Overview
 
-This section documents WordPress, n8n, mail, and social media integrations.
+This section documents WordPress, n8n, mail, and social media integrations for the Kell Creations platform.
+
+## Current State
+
+No formal integration documentation has been published yet. Integration patterns are described at the architecture level in the [Enterprise Integration & Orchestration Architecture](../architecture/containers/enterprise-integration-orchestration-architecture.md) and implemented in the `feature_wordpress` package.
+
+## Existing Integrations
+
+### Implemented
+
+| Integration          | Package             | Protocol  | Status              |
+| -------------------- | ------------------- | --------- | ------------------- |
+| WooCommerce REST API | `feature_wordpress` | HTTP/REST | ✅ Production-ready |
+
+### Architecturally defined but not implemented
+
+| Integration     | Architecture Reference              | Notes                                     |
+| --------------- | ----------------------------------- | ----------------------------------------- |
+| Facebook API    | Social Media Management Components  | `feature_social` is stub only             |
+| Instagram API   | Social Media Management Components  | `feature_social` is stub only             |
+| X (Twitter) API | Social Media Management Components  | `feature_social` is stub only             |
+| n8n Workflows   | Enterprise Integration Architecture | No workflow automation integration exists |
+| Mail Server     | Enterprise Integration Architecture | No programmatic mail integration exists   |
+
+## Recommendations
+
+!!! info "Last analyzed: 2026-05-22"
+
+### 1. Document the WooCommerce integration pattern
+
+**Priority:** High
+
+The WooCommerce integration in `feature_wordpress` is the most mature integration and establishes patterns that future integrations should follow (API client abstraction, repository interface, fake/real runtime selection). This pattern should be formally documented as a reference for future integration work.
+
+### 2. Define integration contracts before implementation
+
+**Priority:** Medium
+
+The `integrations` package exists as a stub. Before implementing new integrations, define shared abstractions for:
+
+- API client lifecycle (creation, authentication, error handling)
+- Rate limiting and retry patterns
+- Response mapping conventions
+- Integration health checking
+
+### 3. Document n8n workflow inventory
+
+**Priority:** Low
+
+n8n is referenced in the architecture as the workflow automation platform. If any n8n workflows are currently active, they should be documented here with their triggers, actions, and dependencies.
+
+### 4. Plan social media API integration
+
+**Priority:** Low
+
+Social media platform APIs (Facebook, Instagram, X) are referenced in the architecture but require individual integration documentation covering:
+
+- API authentication requirements
+- Rate limits and quotas
+- Content format requirements per platform
+- Platform-specific publishing rules
+
+## Relationship to Architecture
+
+Integration documentation should align with:
+
+- [Enterprise Integration & Orchestration Architecture](../architecture/containers/enterprise-integration-orchestration-architecture.md)
+- [Enterprise Shared Services](../architecture/containers/enterprise-services.md)
+- Component views for each application domain

docs/operations/index.md

@@ -1,3 +1,108 @@
 # Operations Overview
 
-This section contains operational runbooks and business procedures.
+This section contains operational runbooks, CI/CD documentation, and business procedures for the Kell Creations platform.
+
+## Current Operational Documentation
+
+| Document                                          | Purpose                                              | Status           |
+| ------------------------------------------------- | ---------------------------------------------------- | ---------------- |
+| [CI/CD Workflow](cicd-workflow.md)                | Defines the documentation publishing pipeline        | ✅ Comprehensive |
+| [Architecture Workflow](architecture-workflow.md) | Defines the diagram authoring and publishing process | ✅ Complete      |
+
+## Analysis Findings
+
+!!! info "Last analyzed: 2026-05-22"
+
+### Confirmed strengths
+
+1. **CI/CD documentation is thorough** — The CI/CD workflow document covers platforms, runner architecture, branch behavior, troubleshooting, permissions, and security considerations
+2. **Architecture workflow is well-defined** — Clear step-by-step process for creating and publishing diagrams
+3. **Four Forgejo Actions workflows are operational** — `publish-docs.yml`, `validate-docs.yml`, `flutter-analyze.yml`, `flutter-test.yml`
+
+### Gaps and recommendations
+
+#### 1. No operational runbooks
+
+**Priority:** Medium
+
+No runbooks exist for common operational tasks such as:
+
+- Server health checks and restart procedures
+- Forgejo runner maintenance and token rotation
+- PlantUML server maintenance
+- MkDocs container updates
+- Backup and recovery procedures
+- SSL certificate renewal
+- DNS and reverse proxy configuration
+
+**Recommendation:** Create lightweight runbooks for the most critical operations first. Suggested initial candidates:
+
+| Candidate                      | Description                                                                      |
+| ------------------------------ | -------------------------------------------------------------------------------- |
+| Runner maintenance runbook     | How to check, restart, re-register, and rotate tokens for Forgejo runners        |
+| Documentation host maintenance | Docker container updates, published site integrity checks, disk space monitoring |
+| Incident response procedure    | What to do when the docs site, Git, or runners are down                          |
+
+#### 2. No monitoring or alerting documentation
+
+**Priority:** Medium
+
+No documentation exists for how to detect or respond to:
+
+- CI/CD pipeline failures
+- Documentation site downtime
+- Runner service failures
+- Disk space or resource exhaustion
+
+**Recommendation:** Document current monitoring capabilities (even if manual) and identify candidates for automated alerting.
+
+#### 3. Architecture workflow is incomplete
+
+**Priority:** Low
+
+The architecture workflow document at `docs/operations/architecture-workflow.md` ends at step 4 (validate repository state) without covering:
+
+- Commit and push procedures
+- CI/CD pipeline verification
+- Published site verification
+- Diagram review process
+
+**Recommendation:** Complete the remaining workflow steps to match the level of detail in the CI/CD workflow document.
+
+#### 4. Local development setup not documented
+
+**Priority:** Low
+
+No documentation covers how to set up a local development environment for:
+
+- MkDocs local preview (including the PlantUML render step)
+- Flutter development environment setup
+- Forgejo runner local testing
+
+**Recommendation:** Add a developer setup guide, particularly noting that `docs/images/` is a CI/CD build artifact and local MkDocs builds require manual PlantUML rendering.
+
+#### 5. CI/CD validation could be expanded
+
+**Priority:** Low
+
+The CI/CD workflow document itself identifies future enhancements that remain unimplemented:
+
+- Broken-link validation
+- Markdown linting integration
+- PlantUML diagram validation
+- Required document metadata checks
+- Notification hooks for failed publishes
+
+**Recommendation:** Prioritize Markdown linting and link checking as the highest-value additions to the validation pipeline.
+
+## Recommended Procedures
+
+The following operational procedures are candidates for formal documentation using the procedure template at `policies/templates/procedure-template.md`:
+
+| Candidate ID   | Title                                    | Priority |
+| -------------- | ---------------------------------------- | -------- |
+| KC-PRO-IT-001  | Forgejo Runner Maintenance Procedure     | Medium   |
+| KC-PRO-IT-002  | Documentation Host Maintenance Procedure | Medium   |
+| KC-PRO-OPS-001 | Incident Response Procedure              | Medium   |
+| KC-PRO-IT-003  | Local Development Setup Procedure        | Low      |
+| KC-PRO-OPS-002 | Backup and Recovery Procedure            | Low      |

docs/policies/index.md

@@ -25,6 +25,49 @@ The initial governance set includes:
 - Document Control Policy
 - Policy Review and Retirement Procedure
 
+## Analysis Findings
+
+!!! info "Last analyzed: 2026-05-22"
+
+### Confirmed strengths
+
+1. **Well-structured repository** — The `policies/` directory follows a clear lifecycle model with properly separated stages (drafts, review, active, retired)
+2. **Comprehensive templates** — Five document type templates are available (policy, procedure, standard, form, exception) with consistent YAML front matter
+3. **Domain categorization** — All lifecycle directories include subdirectories for 9 business domains (ecommerce, finance, governance, IT, manufacturing, marketing, operations, privacy, security)
+4. **Register structure** — Four CSV registers exist for policy tracking (policy register, control log, review calendar, exception register)
+5. **Active governance documents** — 2 foundational governance documents are published and active with complete metadata
+
+### Issues identified
+
+#### 1. Policy register CSVs are empty
+
+**Severity:** High
+
+All four register CSVs contain headers only with no data rows, despite 2 active governance documents existing:
+
+- `policy-register.csv` — should have entries for `KC-POL-GOV-001` and `KC-PRO-GOV-001`
+- `document-control-log.csv` — should record the initial publication of both documents
+- `review-calendar.csv` — should show next review dates (both set to 2027-04-03)
+- `exception-register.csv` — may remain empty if no exceptions exist
+
+**Recommendation:** Populate the registers immediately. The Document Control Policy (`KC-POL-GOV-001`) itself requires that active documents be referenced in the document register and control log.
+
+#### 2. No evidence records exist
+
+**Severity:** Medium
+
+The `evidence/` directory has subdirectories for approvals, exceptions, retirement records, and reviews, but all are empty. The 2 active governance documents were approved on 2026-04-03 but no approval evidence is stored.
+
+**Recommendation:** Create initial approval evidence records for the existing governance documents.
+
+#### 3. Governance documents are only domain with active content
+
+**Severity:** Informational
+
+All other domain directories (ecommerce, finance, IT, manufacturing, marketing, operations, privacy, security) are empty across all lifecycle stages. This is expected given the platform's maturity but should be tracked for future planning.
+
+**Recommendation:** Prioritize standards and procedures identified in the [Standards Overview](../standards/index.md) and [Operations Overview](../operations/index.md) as the next candidates for policy repository content.
+
 ## Notes
 
 This section documents the governance layer that supports controlled business operations for Kell Creations. Future additions should include standards, procedures, guidelines, forms, and exception records across governance, operations, ecommerce, marketing, manufacturing, finance, IT, security, and privacy.

docs/standards/index.md

@@ -1,3 +1,50 @@
 # Standards Overview
 
 This section contains technical, documentation, and business standards.
+
+## Current State
+
+No formal standards documents have been published yet. The following standards are applied implicitly through existing architecture, operations, and development documentation but have not been formalized as controlled standards documents.
+
+## Recommended Standards
+
+The following standards were identified through project analysis as candidates for formal documentation. Each aligns to the policy repository naming convention (`KC-STD-<DOMAIN>-<NUMBER>`) and can be created using the standard template at `policies/templates/standard-template.md`.
+
+### Documentation standards
+
+| Candidate ID   | Title                                      | Priority | Notes                                                                                                             |
+| -------------- | ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| KC-STD-GOV-001 | Documentation Naming and Metadata Standard | High     | Formalize the YAML front matter requirements already defined in the policy repository README                      |
+| KC-STD-GOV-002 | Architecture Documentation Standard        | Medium   | Formalize the C4 diagram documentation pattern (purpose, diagram source, diagram, elements, notes) already in use |
+| KC-STD-IT-001  | Markdown Authoring Standard                | Low      | Formalize linting rules (`.markdownlint.json`), heading conventions, and link patterns                            |
+
+### Development standards
+
+| Candidate ID  | Title                              | Priority | Notes                                                                                                |
+| ------------- | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| KC-STD-IT-002 | Flutter Package Structure Standard | High     | Formalize the domain/application/data/presentation layer pattern used across feature packages        |
+| KC-STD-IT-003 | Test Coverage Standard             | Medium   | Formalize baseline coverage expectations and reporting; currently visibility-only with no thresholds |
+| KC-STD-IT-004 | Git Branching and Merge Standard   | Medium   | Formalize the `feat/` branch-per-slice model and PR requirements documented in the development brief |
+| KC-STD-IT-005 | CI/CD Workflow Standard            | Low      | Formalize workflow naming, trigger patterns, and runner label conventions                            |
+
+### Business standards
+
+| Candidate ID   | Title                            | Priority | Notes                                                  |
+| -------------- | -------------------------------- | -------- | ------------------------------------------------------ |
+| KC-STD-MKT-001 | Social Media Publishing Standard | Low      | Referenced in the traceability index as a coverage gap |
+| KC-STD-ECM-001 | Product Publishing Standard      | Low      | Referenced in the traceability index as a coverage gap |
+| KC-STD-OPS-001 | Inventory Adjustment Standard    | Low      | Referenced in the traceability index as a coverage gap |
+
+## Prioritization
+
+Standards should be prioritized based on:
+
+1. **Risk reduction** — Does this standard prevent inconsistency or errors?
+2. **Existing practice** — Is the standard already followed informally?
+3. **Scope of impact** — How many areas of the platform does it affect?
+
+The documentation and development standards are recommended first because they codify practices already in use and reduce the risk of drift as the platform grows.
+
+## Relationship to Policies and Procedures
+
+Standards define measurable requirements and constraints. They are governed by the Document Control Policy (`KC-POL-GOV-001`) and follow the same controlled lifecycle (draft → review → active → retired).

mkdocs.yml

@@ -67,6 +67,7 @@ nav:
   - Operations:
       - Operations Overview: operations/index.md
       - CI/CD Workflow: operations/cicd-workflow.md
+      - Architecture Workflow: operations/architecture-workflow.md
   - Standards:
       - Standards Overview: "standards/index.md"
   - Integrations: