docs: sync master development brief with completed stages and resolved recommendations

- Update current status to Stage 4D complete (Stage 4 complete)

- Add feat/test-coverage-visibility slice entry with coverage baseline

- Set next branch to feat/android-app-shell (Stage 5A)

.forgejo/workflows/flutter-analyze.yml

@@ -0,0 +1,77 @@
+name: Flutter Analyze
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - "**"
+      - "!main"
+
+jobs:
+  analyze:
+    name: Dart Analyze
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/cirruslabs/flutter:stable
+
+    defaults:
+      run:
+        working-directory: kell_creations_apps
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies — core
+        run: cd packages/core && flutter pub get
+
+      - name: Install dependencies — design_system
+        run: cd packages/design_system && flutter pub get
+
+      - name: Install dependencies — feature_wordpress
+        run: cd packages/feature_wordpress && flutter pub get
+
+      - name: Install dependencies — feature_inventory
+        run: cd packages/feature_inventory && flutter pub get
+
+      - name: Install dependencies — feature_orders
+        run: cd packages/feature_orders && flutter pub get
+
+      - name: Install dependencies — feature_policy
+        run: cd packages/feature_policy && flutter pub get
+
+      - name: Install dependencies — kell_web
+        run: cd apps/kell_web && flutter pub get
+
+      - name: Install dependencies — kell_mobile
+        run: cd apps/kell_mobile && flutter pub get
+
+      - name: Analyze — core
+        run: cd packages/core && dart analyze --fatal-infos
+
+      - name: Analyze — design_system
+        run: cd packages/design_system && dart analyze --fatal-infos
+
+      - name: Analyze — feature_wordpress
+        run: cd packages/feature_wordpress && dart analyze --fatal-infos
+
+      - name: Analyze — feature_inventory
+        run: cd packages/feature_inventory && dart analyze --fatal-infos
+
+      - name: Analyze — feature_orders
+        run: cd packages/feature_orders && dart analyze --fatal-infos
+
+      - name: Analyze — feature_policy
+        run: cd packages/feature_policy && dart analyze --fatal-infos
+
+      - name: Analyze — kell_web
+        run: cd apps/kell_web && dart analyze --fatal-infos
+
+      - name: Analyze — kell_mobile
+        run: cd apps/kell_mobile && dart analyze --fatal-infos
+
+      - name: Summary
+        if: always()
+        run: echo "✅ Dart analyze completed for all packages and apps"

.forgejo/workflows/flutter-test.yml

@@ -0,0 +1,162 @@
+name: Flutter Test
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - "**"
+      - "!main"
+
+jobs:
+  test:
+    name: Flutter Tests
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/cirruslabs/flutter:stable
+
+    defaults:
+      run:
+        working-directory: kell_creations_apps
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies — core
+        run: cd packages/core && flutter pub get
+
+      - name: Install dependencies — design_system
+        run: cd packages/design_system && flutter pub get
+
+      - name: Install dependencies — feature_wordpress
+        run: cd packages/feature_wordpress && flutter pub get
+
+      - name: Install dependencies — kell_web
+        run: cd apps/kell_web && flutter pub get
+
+      - name: Test with coverage — core
+        run: |
+          cd packages/core
+          flutter test --coverage --reporter expanded 2>&1 | tee test_output.txt
+          echo ""
+          echo "=== core test summary ==="
+          TOTAL=$(grep -cE '^\s*✓' test_output.txt || echo "0")
+          FAILED=$(grep -cE '^\s*✗' test_output.txt || echo "0")
+          echo "  Passed: $TOTAL"
+          echo "  Failed: $FAILED"
+          # Fail the step if any tests failed
+          if [ "$FAILED" -gt 0 ]; then exit 1; fi
+
+      - name: Test with coverage — design_system
+        run: |
+          cd packages/design_system
+          flutter test --coverage --reporter expanded 2>&1 | tee test_output.txt
+          echo ""
+          echo "=== design_system test summary ==="
+          TOTAL=$(grep -cE '^\s*✓' test_output.txt || echo "0")
+          FAILED=$(grep -cE '^\s*✗' test_output.txt || echo "0")
+          echo "  Passed: $TOTAL"
+          echo "  Failed: $FAILED"
+          if [ "$FAILED" -gt 0 ]; then exit 1; fi
+
+      - name: Test with coverage — feature_wordpress
+        run: |
+          cd packages/feature_wordpress
+          flutter test --coverage --reporter expanded 2>&1 | tee test_output.txt
+          echo ""
+          echo "=== feature_wordpress test summary ==="
+          TOTAL=$(grep -cE '^\s*✓' test_output.txt || echo "0")
+          FAILED=$(grep -cE '^\s*✗' test_output.txt || echo "0")
+          echo "  Passed: $TOTAL"
+          echo "  Failed: $FAILED"
+          if [ "$FAILED" -gt 0 ]; then exit 1; fi
+
+      - name: Test with coverage — kell_web
+        run: |
+          cd apps/kell_web
+          flutter test --coverage --reporter expanded 2>&1 | tee test_output.txt
+          echo ""
+          echo "=== kell_web test summary ==="
+          TOTAL=$(grep -cE '^\s*✓' test_output.txt || echo "0")
+          FAILED=$(grep -cE '^\s*✗' test_output.txt || echo "0")
+          echo "  Passed: $TOTAL"
+          echo "  Failed: $FAILED"
+          if [ "$FAILED" -gt 0 ]; then exit 1; fi
+
+      - name: Aggregate test and coverage report
+        if: always()
+        run: |
+          echo ""
+          echo "╔═══════════════════════════════════════════════════════════╗"
+          echo "║          Flutter Test & Coverage Summary                 ║"
+          echo "╠═══════════════════════════════════════════════════════════╣"
+          echo "║ Package              Pass    Fail    Lines    Coverage   ║"
+          echo "╠═══════════════════════════════════════════════════════════╣"
+
+          TOTAL_PASS=0
+          TOTAL_FAIL=0
+          TOTAL_HIT=0
+          TOTAL_FOUND=0
+
+          for pkg in packages/core packages/design_system packages/feature_wordpress apps/kell_web; do
+            NAME=$(basename "$pkg")
+            OUTPUT="$pkg/test_output.txt"
+            LCOV="$pkg/coverage/lcov.info"
+
+            # Test counts
+            if [ -f "$OUTPUT" ]; then
+              PASS=$(grep -cE '^\s*✓' "$OUTPUT" || echo "0")
+              FAIL=$(grep -cE '^\s*✗' "$OUTPUT" || echo "0")
+            else
+              PASS="—"
+              FAIL="—"
+            fi
+
+            # Coverage from lcov.info
+            if [ -f "$LCOV" ]; then
+              LF=$(grep -oP '(?<=LF:)\d+' "$LCOV" | awk '{s+=$1} END {print s+0}')
+              LH=$(grep -oP '(?<=LH:)\d+' "$LCOV" | awk '{s+=$1} END {print s+0}')
+              if [ "$LF" -gt 0 ]; then
+                PCT=$(awk "BEGIN {printf \"%.1f%%\", ($LH/$LF)*100}")
+              else
+                PCT="N/A"
+              fi
+              LINES="$LH/$LF"
+            else
+              LINES="—"
+              PCT="—"
+              LF=0
+              LH=0
+            fi
+
+            printf "║ %-20s %-7s %-7s %-8s %-10s ║\n" "$NAME" "$PASS" "$FAIL" "$LINES" "$PCT"
+
+            if [ "$PASS" != "—" ]; then TOTAL_PASS=$((TOTAL_PASS + PASS)); fi
+            if [ "$FAIL" != "—" ]; then TOTAL_FAIL=$((TOTAL_FAIL + FAIL)); fi
+            TOTAL_HIT=$((TOTAL_HIT + LH))
+            TOTAL_FOUND=$((TOTAL_FOUND + LF))
+          done
+
+          if [ "$TOTAL_FOUND" -gt 0 ]; then
+            TOTAL_PCT=$(awk "BEGIN {printf \"%.1f%%\", ($TOTAL_HIT/$TOTAL_FOUND)*100}")
+            TOTAL_LINES="$TOTAL_HIT/$TOTAL_FOUND"
+          else
+            TOTAL_PCT="—"
+            TOTAL_LINES="—"
+          fi
+
+          echo "╠═══════════════════════════════════════════════════════════╣"
+          printf "║ %-20s %-7s %-7s %-8s %-10s ║\n" "TOTAL" "$TOTAL_PASS" "$TOTAL_FAIL" "$TOTAL_LINES" "$TOTAL_PCT"
+          echo "╚═══════════════════════════════════════════════════════════╝"
+
+          if [ "$TOTAL_FAIL" -gt 0 ]; then
+            echo ""
+            echo "❌ Some tests failed. See individual package results above."
+            exit 1
+          else
+            echo ""
+            echo "✅ All $TOTAL_PASS tests passed across all packages."
+            echo "📊 Overall line coverage: $TOTAL_PCT ($TOTAL_LINES lines)"
+          fi

.gitignore

@@ -4,3 +4,6 @@ __pycache__/
 .venv/
 .DS_Store
 Thumbs.db
+
+# Flutter test coverage output
+coverage/

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/build_execution_tracker.md

@@ -2,10 +2,10 @@
 
 ## Current status
 
-- main baseline updated through: design-system-shared-widgets (Stage 4A complete)
-- main baseline commit: merge of `feat/design-system-shared-widgets` (2026-05-22)
-- next branch: feat/shared-composition-pattern
-- current stage: Stage 4 — Platform foundations and cross-platform readiness
+- main baseline updated through: test-coverage-visibility (Stage 4D complete — Stage 4 complete)
+- main baseline commit: merge of `feat/test-coverage-visibility` (2026-05-22)
+- next branch: feat/android-app-shell (Stage 5A)
+- current stage: Stage 5 — Android application foundation
 
 ## Slice tracker
 
@@ -111,3 +111,50 @@
 - tests: passed (41/41 design_system, 294/294 feature_wordpress, 24/24 kell_web)
 - analyze: passed (dart analyze — no issues found in design_system and kell_web)
 - brief updated: yes
+
+### feat/shared-composition-pattern
+
+- status: merged to main
+- date: 2026-05-22
+- inspection: complete
+- implementation: complete
+- files changed:
+  - `core/lib/src/app/` — extracted shared composition abstractions (KcAppConfig, KcAppEnvironment, KcAppServices, KcServiceFactory, KcBootstrap, KcAppScope)
+  - `core/lib/core.dart` — expanded barrel exports for app composition
+  - `core/test/core_test.dart` — added 20 tests for shared composition abstractions
+  - `kell_web/` — updated to use core composition abstractions
+- tests: passed (20/20 core, 41/41 design_system, 294/294 feature_wordpress, 24/24 kell_web)
+- analyze: passed
+- brief updated: yes
+
+### feat/flutter-cicd
+
+- status: merged to main
+- date: 2026-05-22
+- inspection: complete
+- implementation: complete
+- files changed:
+  - `.forgejo/workflows/flutter-analyze.yml` — new Forgejo Actions workflow for dart analyze on all 8 packages/apps
+  - `.forgejo/workflows/flutter-test.yml` — new Forgejo Actions workflow for flutter test per package with aggregate pass/fail summary
+  - `kell_creations_apps/tools/run_all_tests.sh` — new local CI helper script with optional --analyze flag
+  - `kell_creations_apps/tools/README.md` — documents scripts and CI workflow inventory
+- tests: passed (20/20 core, 41/41 design_system, 294/294 feature_wordpress, 24/24 kell_web — 379 total)
+- analyze: passed (dart analyze — no issues found across all 8 packages/apps)
+- brief updated: yes
+
+### feat/test-coverage-visibility
+
+- status: merged to main
+- date: 2026-05-22
+- inspection: complete
+- implementation: complete
+- files changed:
+  - `.forgejo/workflows/flutter-test.yml` — enhanced to run flutter test --coverage, parse lcov.info, report per-package line coverage percentages in aggregate summary table
+  - `kell_creations_apps/tools/collect_coverage.sh` — new local coverage helper script with summary table
+  - `kell_creations_apps/tools/README.md` — documented collect_coverage.sh script
+  - `.gitignore` — added coverage/ directories
+  - `docs/development/master_development_brief.md` — marked Stage 4D complete, documented baseline coverage table, updated next branch to Stage 5A, partially resolved improvement #5
+- tests: passed (20/20 core, 41/41 design_system, 294/294 feature_wordpress, 24/24 kell_web — 379 total)
+- analyze: passed
+- coverage baseline: core 85.7%, design_system 100.0%, feature_wordpress 84.7%, kell_web 54.1%, overall 78.4%
+- brief updated: yes

docs/development/master_development_brief.md

@@ -48,8 +48,8 @@ Rules:
 - `apps/kell_web` exists — active, wired to shared packages.
 - `apps/kell_mobile` exists — scaffolded as default Flutter template, **not yet integrated** with shared packages.
 - Shared packages include:
-  - `core` — shared domain/application abstractions
-  - `design_system` — theme (colors, spacing, theme) and shared widgets (KcCard, KcStatusChip)
+  - `core` — shared domain/application abstractions and cross-platform composition pattern (`KcAppConfig`, `KcAppServices`, `KcBootstrap`, `KcAppScope`)
+  - `design_system` — theme (`KcColors`, `KcSpacing`, `KcTheme`), typography (`KcTypography`), layout (`KcBreakpoints`), and 7 shared widgets (`KcCard`, `KcStatusChip`, `KcEmptyState`, `KcSectionHeader`, `KcSummaryCard`, `KcLoadingState`, `KcErrorState`)
   - `feature_inventory` — domain, application, data (fake), and presentation layers
   - `feature_wordpress` — domain, application, data (fake + WooCommerce), and presentation layers (most mature feature)
   - `feature_orders` — domain, application, data (fake), and presentation layers
@@ -61,7 +61,7 @@ Rules:
   - `feature_finance` — financial analysis feature (stub only)
   - `feature_mrp` — craft manufacturing/MRP feature (stub only)
   - `feature_social` — social media management feature (stub only)
-- `tools/` directory exists but is empty.
+- `tools/` directory contains CI helper scripts (`run_all_tests.sh`, `collect_coverage.sh`, `README.md`).
 - App shell, routing, dashboard, reusable shell widgets, `AppServices`, and `AppScope` are implemented.
 - Dashboard uses app-composed repository data.
 - Vertical slices exist for Inventory, Products/Publishing, Orders, and Policy/Governance.
@@ -94,6 +94,8 @@ Rules:
 - ✅ List efficiency improvements landed (Stage 3B complete — merged `feat/list-efficiency-improvements` → `main`, 2026-05-22). Stage 3 complete.
 - ✅ Design system expansion and shared widget migration landed (Stage 4A complete — merged `feat/design-system-shared-widgets` → `main`, 2026-05-22).
 - ✅ Cross-platform shell composition strategy landed (Stage 4B complete — merged `feat/shared-composition-pattern` → `main`, 2026-05-22).
+- ✅ Flutter CI/CD pipeline landed (Stage 4C complete — merged `feat/flutter-cicd` → `main`, 2026-05-22).
+- ✅ Test coverage visibility landed (Stage 4D complete — merged `feat/test-coverage-visibility` → `main`, 2026-05-22).
 
 ### Current narrow edit capabilities on `main`
 
@@ -114,12 +116,24 @@ Rules:
 - latest reported count for `design_system`: `41/41 passed`
 - latest reported count for `feature_wordpress`: `294/294 passed`
 - latest reported count for `kell_web`: `24/24 passed`
-- baseline commit: merge of `feat/shared-composition-pattern` (2026-05-22)
+- baseline commit: merge of `feat/test-coverage-visibility` (2026-05-22)
+
+#### Baseline test coverage (established 2026-05-22)
+
+| Package             | Tests   | Lines Hit | Lines Found | Coverage  |
+| ------------------- | ------- | --------- | ----------- | --------- |
+| `core`              | 20      | 42        | 49          | 85.7%     |
+| `design_system`     | 41      | 88        | 88          | 100.0%    |
+| `feature_wordpress` | 294     | 857       | 1012        | 84.7%     |
+| `kell_web`          | 24      | 191       | 353         | 54.1%     |
+| **Total**           | **379** | **1178**  | **1502**    | **78.4%** |
+
+No minimum thresholds are enforced — this is visibility-only tracking. Coverage is measured via `flutter test --coverage` (generates `lcov.info`) and reported in the CI workflow summary table.
 
 ### Next recommended branch
 
-**`feat/flutter-cicd`** — Stage 4C: Flutter CI/CD pipeline.
-Branch from latest `main`. Stage 4B (cross-platform shell composition) is complete.
+**`feat/android-app-shell`** — Stage 5A: Android app shell and bootstrap.
+Branch from latest `main`. Stage 4 (Platform foundations and cross-platform readiness) is complete.
 
 ---
 
@@ -234,64 +248,20 @@ Invest in shared foundations now so that the Android expansion (Stage 5) and all
 > Merged `feat/design-system-shared-widgets` → `main` (2026-05-22).
 > Migrated `EmptyStatePanel`, `SectionHeader`, and `SummaryCard` from `kell_web/lib/shell/widgets/` into `design_system` as `KcEmptyState`, `KcSectionHeader`, and `KcSummaryCard`. Added `KcTypography` shared typography scale, `KcBreakpoints` responsive layout breakpoint utilities, `KcLoadingState` and `KcErrorState` shared state widgets. Updated `kell_web` dashboard to use design_system widgets directly; shell widget files now contain backward-compatible typedefs. Theme updated to use `KcTypography.applyKcTypography()`. 41 new design_system tests added (41 total `design_system` tests, 294 `feature_wordpress` tests, 24 `kell_web` tests — all passing). Analyze clean.
 
-#### Stage 4B — Cross-platform shell composition strategy
+#### ~~Stage 4B — Cross-platform shell composition strategy~~ ✅ COMPLETE
 
-##### Goal
+> Merged `feat/shared-composition-pattern` → `main` at `0a0abc2` (2026-05-22).
+> Extracted shared composition abstractions into `core` package: `KcAppConfig`, `KcAppEnvironment`, `KcAppServices` (abstract), `KcServiceFactory<T>`, `KcBootstrap`, `KcAppScope<T>`. Updated `kell_web` to delegate to shared types via backward-compatible typedefs (`AppConfig`, `AppEnvironment`, `AppServices`, `AppScope`, `Bootstrap`). Contract for new app targets documented in `kell_creations_apps/docs/composition-strategy.md`. `kell_web` runtime behavior unchanged. 20 core tests added covering all composition abstractions (20/20 core, 41/41 design_system, 294/294 feature_wordpress, 24/24 kell_web — all passing). Analyze clean.
 
-Extract or document a shared app composition pattern so `kell_mobile` can mirror the `kell_web` architecture without forking logic.
+#### ~~Stage 4C — Flutter CI/CD pipeline~~ ✅ COMPLETE
 
-##### Requirements
+> Merged `feat/flutter-cicd` → `main` (2026-05-22).
+> Added Forgejo Actions workflows: `flutter-analyze.yml` (runs `dart analyze --fatal-infos` on all 8 packages/apps) and `flutter-test.yml` (runs `flutter test` per package with per-package pass/fail count and aggregate summary table). Workflows trigger on PRs to main and all non-main branch pushes using `ghcr.io/cirruslabs/flutter:stable` container. Populated `tools/` directory with `run_all_tests.sh` (local test runner with optional `--analyze` flag) and `README.md` documenting scripts and CI workflow inventory. All existing tests passing (20 core, 41 design_system, 294 feature_wordpress, 24 kell_web — 379 total). Analyze clean.
 
-- evaluate whether `AppServices`, `AppScope`, `AppConfig`, and `Bootstrap` should move to a shared package (e.g., `core` or new `app_shell`) or remain duplicated with a documented contract
-- if extracting: create shared composition abstractions in the chosen package
-- if duplicating: document the contract explicitly so `kell_mobile` follows the same pattern
-- do not change runtime behavior of `kell_web`
+#### ~~Stage 4D — Test coverage visibility~~ ✅ COMPLETE
 
-##### Definition of done
-
-- composition strategy is decided and documented
-- shared abstractions extracted or duplication contract documented
-- `kell_web` still works identically
-- analyze clean, existing tests passing
-
-#### Stage 4C — Flutter CI/CD pipeline
-
-##### Goal
-
-Establish automated validation for Flutter applications in Forgejo Actions.
-
-##### Requirements
-
-- add Forgejo Actions workflow for `dart analyze` on PRs
-- add Forgejo Actions workflow for `flutter test` execution on PRs (per package)
-- add basic test result reporting (pass/fail count per package)
-- ensure workflows work for both web and Android targets
-- populate `tools/` directory with any CI helper scripts if needed
-
-##### Definition of done
-
-- PRs trigger automated analyze and test runs
-- test counts are reported in workflow output
-- workflow files committed under `.forgejo/workflows/`
-- `tools/` directory populated or removed if not needed
-
-#### Stage 4D — Test coverage visibility
-
-##### Goal
-
-Introduce lightweight test coverage tracking across packages.
-
-##### Requirements
-
-- add coverage measurement to CI pipeline (at minimum: total tests and pass rate per package)
-- document current baseline coverage in this brief or a companion document
-- do not enforce minimum thresholds yet — visibility first
-
-##### Definition of done
-
-- coverage data is generated and visible in CI output
-- baseline coverage documented
-- no regressions in existing tests
+> Merged `feat/test-coverage-visibility` → `main` (2026-05-22).
+> Enhanced `flutter-test.yml` CI workflow to run `flutter test --coverage` and parse `lcov.info` files, producing an aggregate summary table with per-package pass/fail counts and line coverage percentages. Added `collect_coverage.sh` local coverage helper script and updated `tools/README.md`. Established baseline coverage: core 85.7% (42/49), design_system 100.0% (88/88), feature_wordpress 84.7% (857/1012), kell_web 54.1% (191/353) — overall 78.4% (1178/1502). No minimum thresholds enforced — visibility first. All 379 tests passing. Analyze clean. Stage 4 complete.
 
 ---
 
@@ -443,60 +413,39 @@ The following packages exist as scaffolded stubs with no implementation. Each ne
 
 **Recommendation:** Add a **Stage 8 — Infrastructure package activation** to the roadmap covering `auth`, `data`, and `integrations` before expanding into new feature domains.
 
-### 2. Design system expansion
+### ~~2. Design system expansion~~ ✅ RESOLVED
 
-The `design_system` package currently contains:
+> Addressed in **Stage 4A** (Design system expansion and shared widget migration), merged 2026-05-22.
+> All previously identified gaps have been resolved:
+>
+> - ✅ Shared typography scale → `KcTypography` with full Material 3 hierarchy and `applyKcTypography()` helper
+> - ✅ Responsive layout utilities → `KcBreakpoints` with compact/medium/expanded/large queries and grid column helper
+> - ✅ Shared empty state, loading state, error state patterns → `KcEmptyState`, `KcLoadingState`, `KcErrorState`
+> - ✅ Shell widgets migrated → `EmptyStatePanel`, `SectionHeader`, `SummaryCard` moved from `kell_web` to `design_system` as `KcEmptyState`, `KcSectionHeader`, `KcSummaryCard`; backward-compatible typedefs retained in `kell_web`
+>
+> The `design_system` package now contains: theme (`KcColors`, `KcSpacing`, `KcTheme`), typography (`KcTypography`), layout (`KcBreakpoints`), and 7 widgets (`KcCard`, `KcStatusChip`, `KcEmptyState`, `KcSectionHeader`, `KcSummaryCard`, `KcLoadingState`, `KcErrorState`). 41 tests, 100% line coverage.
+>
+> **Remaining gap:** No shared button/action component library. This can be addressed in a future stage as needed.
 
-- Theme: `KcColors`, `KcSpacing`, `KcTheme`
-- Widgets: `KcCard`, `KcStatusChip`
+### ~~3. Cross-platform shell composition strategy~~ ✅ RESOLVED
 
-**Gaps identified:**
+> Addressed in **Stage 4B** (Cross-platform shell composition strategy), merged `feat/shared-composition-pattern` → `main` at `0a0abc2` (2026-05-22).
+> Shared composition abstractions extracted into `core` package: `KcAppConfig`, `KcAppEnvironment`, `KcAppServices` (abstract), `KcServiceFactory<T>`, `KcBootstrap`, `KcAppScope<T>`. `kell_web` updated to delegate to shared types via backward-compatible typedefs. Contract for new app targets (including `kell_mobile`) documented in `kell_creations_apps/docs/composition-strategy.md`. 20 core tests passing. Analyze clean.
 
-- No shared typography scale
-- No shared button/action component library
-- No responsive layout utilities for cross-platform (web + mobile)
-- No shared empty state, loading state, or error state patterns
-- Shell widgets (`EmptyStatePanel`, `SectionHeader`, `SummaryCard`) live in `kell_web` app rather than `design_system`
+### ~~4. CI/CD for Flutter applications~~ ✅ RESOLVED
 
-**Recommendation:** Now addressed in **Stage 4A** (Design system expansion and shared widget migration). Migrate reusable shell widgets into `design_system` and add responsive layout primitives before the Android expansion in Stage 5.
+> Addressed in **Stage 4C** (Flutter CI/CD pipeline), merged `feat/flutter-cicd` → `main` at `6a6323e` (2026-05-22).
+> Two Forgejo Actions workflows established: `flutter-analyze.yml` (runs `dart analyze --fatal-infos` on all 8 packages/apps) and `flutter-test.yml` (runs `flutter test` per package with aggregate summary table). Workflows trigger on PRs to main and all non-main branch pushes. Local CI helper scripts added to `tools/`.
+>
+> **Remaining gap:** Flutter build validation (web + Android) is not yet automated in CI. This can be added as Android work progresses in Stage 5.
 
-### 3. Cross-platform shell composition strategy
+### 5. ~~Test coverage visibility and quality gates~~ ✅ PARTIALLY RESOLVED
 
-`kell_web` uses a well-structured composition pattern (`AppServices`, `AppScope`, `AppConfig`, `Bootstrap`). `kell_mobile` has none of this — it's a default counter app.
+> Automated test count reporting and line coverage measurement now addressed in Stage 4D (test coverage visibility). CI workflow produces per-package pass/fail counts and coverage percentages. Baseline documented. Minimum threshold enforcement and trend tracking remain future enhancements.
 
-**Recommendation:** Extract a shared shell composition pattern or at minimum define a documented convention so that `kell_mobile` mirrors the `kell_web` architecture. Consider whether `AppServices`, `AppScope`, and bootstrap logic should move to a shared `core` or `app_shell` package, or remain duplicated with a documented contract.
+### ~~6. Build execution tracker synchronization~~ ✅ RESOLVED
 
-### 4. CI/CD for Flutter applications
-
-Currently, CI/CD exists only for MkDocs documentation publishing. There is no automated pipeline for:
-
-- Flutter `dart analyze` on PRs
-- Flutter test execution on PRs
-- Flutter build validation (web + Android)
-- Test result reporting or quality gates
-
-**Recommendation:** Now addressed in **Stage 4C** (Flutter CI/CD pipeline). Establish Flutter CI/CD in Forgejo Actions before the Android expansion in Stage 5 adds more surfaces to validate.
-
-### 5. Test coverage visibility and quality gates
-
-Test counts are tracked manually in this brief (e.g., `294/294 passed`). There is no:
-
-- Automated test count reporting
-- Coverage measurement
-- Minimum coverage threshold enforcement
-- Test trend tracking across slices
-
-**Recommendation:** Introduce coverage tooling and reporting as part of CI/CD establishment. Even lightweight coverage tracking (total tests, pass rate per package) would improve confidence during the Android expansion.
-
-### 6. Build execution tracker synchronization
-
-The `build_execution_tracker.md` is stale:
-
-- Shows `feat/multi-select-groundwork` as "queued" when it was merged 2026-05-22
-- Does not include `feat/list-efficiency-improvements` at all
-- `current status` section references Stage 3 as current when Stage 3 is complete
-
-**Recommendation:** Update the tracker immediately and consider whether the tracker should be auto-generated or at minimum updated as part of the standard slice completion checklist.
+> The `build_execution_tracker.md` has been fully updated through Stage 4D. All 10 merged branches are tracked with status, dates, files changed, test counts, and analysis results. Current status correctly reflects Stage 4 complete and next branch as `feat/android-app-shell` (Stage 5A). Updated as part of the Stage 4C/4D merge cycle (2026-05-22).
 
 ### 7. Image and media management
 
@@ -514,17 +463,55 @@ No monitoring, error tracking, or analytics strategy exists for the Flutter appl
 
 **Recommendation:** Add lightweight error reporting and observability as a future stage, particularly important before any production WP-mode deployment beyond a single operator.
 
-### 9. Empty tools directory
+### 9. ~~Empty tools directory~~ ✅ RESOLVED
 
-The `tools/` directory under `kell_creations_apps` exists but contains nothing.
+> Now populated with `run_all_tests.sh` and `README.md` as part of Stage 4C (Flutter CI/CD pipeline).
 
-**Recommendation:** Either populate with development tooling (code generation scripts, analysis helpers, CI scripts) or remove to avoid confusion. If CI/CD scripts are planned, this is a natural home.
+### ~~10. Missing feature parity documentation~~ ✅ PARTIALLY RESOLVED
 
-### 10. Missing feature parity documentation
+> A **feature maturity matrix** has been added to this brief (see **Appendix: Feature maturity matrix** at the end of this document). It maps all 12 packages across domain, application, data (fake/real), presentation, test count, and maturity level. Added 2026-05-22 during full project analysis.
+>
+> **Remaining gap:** The matrix does not yet map architecture documentation aspirations to implementation status per feature (e.g., which architecture-described capabilities exist vs. are missing within each feature package). This can be expanded as feature packages mature.
 
-The architecture documentation describes rich capabilities across all domains (Inventory, MRP, WordPress, Social Media, Financial Analysis), but actual implementation maturity varies dramatically. Only `feature_wordpress` has substantial implementation.
+### 11. Policy register CSVs are empty
 
-**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.
+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.
 
 ---
 
@@ -594,4 +581,4 @@ Working rules:
 | `data`              | ❌ Stub      | N/A               | N/A         | ❌ None        | N/A                                                | None    | **Scaffolded only**  |
 | `integrations`      | ❌ Stub      | N/A               | N/A         | ❌ None        | N/A                                                | None    | **Scaffolded only**  |
 | `design_system`     | N/A          | N/A               | N/A         | N/A            | ✅ Expanded (theme, typography, layout, 7 widgets) | 41      | **Foundation ready** |
-| `core`              | ✅ Partial   | N/A               | N/A         | N/A            | N/A                                                | 20      | **Foundation ready** |
+| `core`              | ✅ Partial   | ✅ Composition    | N/A         | N/A            | N/A                                                | 20      | **Foundation ready** |

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).

kell_creations_apps/tools/README.md

@@ -0,0 +1,83 @@
+# Tools
+
+CI/CD helper scripts for the Kell Creations Flutter monorepo.
+
+## Scripts
+
+### `run_all_tests.sh`
+
+Runs `flutter test` across all testable packages and apps, producing a per-package pass/fail summary.
+
+**Usage:**
+
+```bash
+# From kell_creations_apps/ directory
+./tools/run_all_tests.sh           # Run tests only
+./tools/run_all_tests.sh --analyze # Run dart analyze + tests
+```
+
+**What it does:**
+
+1. Installs dependencies (`flutter pub get`) for all packages and apps.
+2. Optionally runs `dart analyze --fatal-infos` on each package/app.
+3. Runs `flutter test --reporter expanded` for packages with tests.
+4. Prints an aggregate pass/fail summary table.
+
+**Adding new packages:**
+
+When a new package gains tests, add its path to the `TESTABLE` array in the script. For packages that should be analyzed but have no tests yet, add to the `ANALYZABLE` array only.
+
+**Exit codes:**
+
+- `0` — all tests passed (and analyze clean, if `--analyze` was used)
+- `1` — one or more failures detected
+
+### `collect_coverage.sh`
+
+Runs `flutter test --coverage` across all testable packages and apps, parses the generated `lcov.info` files, and produces a combined summary table with test counts and line coverage percentages.
+
+**Usage:**
+
+```bash
+# From kell_creations_apps/ directory
+./tools/collect_coverage.sh
+```
+
+**What it does:**
+
+1. Installs dependencies (`flutter pub get`) for testable packages.
+2. Runs `flutter test --coverage --reporter expanded` for each package.
+3. Parses `coverage/lcov.info` to extract lines hit / lines found per package.
+4. Prints an aggregate summary table with pass/fail counts and coverage percentages.
+
+**Output example:**
+
+```
+╔═══════════════════════════════════════════════════════════╗
+║          Flutter Test & Coverage Summary                 ║
+╠═══════════════════════════════════════════════════════════╣
+║ Package              Pass    Fail    Lines    Coverage   ║
+╠═══════════════════════════════════════════════════════════╣
+║ core                 20      0       120/150  80.0%      ║
+║ design_system        41      0       95/110   86.4%      ║
+║ ...                                                      ║
+╠═══════════════════════════════════════════════════════════╣
+║ TOTAL                379     0       500/600  83.3%      ║
+╚═══════════════════════════════════════════════════════════╝
+```
+
+**Exit codes:**
+
+- `0` — all tests passed
+- `1` — one or more failures detected
+
+## CI Workflows
+
+The corresponding Forgejo Actions workflows live in `.forgejo/workflows/`:
+
+| Workflow              | Trigger           | Purpose                                      |
+| --------------------- | ----------------- | -------------------------------------------- |
+| `flutter-analyze.yml` | PRs and branches  | Runs `dart analyze` on all packages and apps |
+| `flutter-test.yml`    | PRs and branches  | Runs `flutter test` with result reporting    |
+| `validate-docs.yml`   | Non-main branches | Validates MkDocs documentation build         |
+| `publish-docs.yml`    | Push to main      | Publishes documentation to docs host         |

kell_creations_apps/tools/collect_coverage.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────────────
+# collect_coverage.sh — Run flutter test --coverage and report results
+#
+# Usage:
+#   ./tools/collect_coverage.sh           # Run from kell_creations_apps/
+#
+# Generates coverage/lcov.info per package, then prints a summary table
+# showing test pass/fail counts and line coverage percentage.
+#
+# Exit codes:
+#   0 — all tests passed
+#   1 — one or more failures
+# ──────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Packages/apps with tests (add new ones here as they gain tests)
+TESTABLE=(
+  packages/core
+  packages/design_system
+  packages/feature_wordpress
+  apps/kell_web
+)
+
+OVERALL_EXIT=0
+
+# ── Dependency install ───────────────────────────────────────────────
+echo ""
+echo "══════════════════════════════════════"
+echo "  Installing dependencies"
+echo "══════════════════════════════════════"
+
+for pkg in "${TESTABLE[@]}"; do
+  echo "  → $pkg"
+  (cd "$ROOT_DIR/$pkg" && flutter pub get --no-example) > /dev/null 2>&1
+done
+
+# ── Tests with coverage ─────────────────────────────────────────────
+echo ""
+echo "══════════════════════════════════════"
+echo "  Running flutter test --coverage"
+echo "══════════════════════════════════════"
+
+declare -A RESULTS_PASS
+declare -A RESULTS_FAIL
+declare -A RESULTS_LH
+declare -A RESULTS_LF
+declare -A RESULTS_PCT
+
+for pkg in "${TESTABLE[@]}"; do
+  NAME=$(basename "$pkg")
+  echo ""
+  echo "  ── $NAME ──"
+
+  TMPFILE=$(mktemp)
+  if (cd "$ROOT_DIR/$pkg" && flutter test --coverage --reporter expanded 2>&1) | tee "$TMPFILE"; then
+    : # tests passed
+  else
+    OVERALL_EXIT=1
+  fi
+
+  PASS=$(grep -cE '^\s*✓' "$TMPFILE" 2>/dev/null || echo "0")
+  FAIL=$(grep -cE '^\s*✗' "$TMPFILE" 2>/dev/null || echo "0")
+  RESULTS_PASS[$NAME]=$PASS
+  RESULTS_FAIL[$NAME]=$FAIL
+  rm -f "$TMPFILE"
+
+  # Parse lcov.info for coverage
+  LCOV="$ROOT_DIR/$pkg/coverage/lcov.info"
+  if [ -f "$LCOV" ]; then
+    LF=$(grep -oP '(?<=LF:)\d+' "$LCOV" | awk '{s+=$1} END {print s+0}')
+    LH=$(grep -oP '(?<=LH:)\d+' "$LCOV" | awk '{s+=$1} END {print s+0}')
+    if [ "$LF" -gt 0 ]; then
+      PCT=$(awk "BEGIN {printf \"%.1f\", ($LH/$LF)*100}")
+    else
+      PCT="0.0"
+    fi
+  else
+    LF=0
+    LH=0
+    PCT="—"
+  fi
+  RESULTS_LH[$NAME]=$LH
+  RESULTS_LF[$NAME]=$LF
+  RESULTS_PCT[$NAME]=$PCT
+done
+
+# ── Summary ──────────────────────────────────────────────────────────
+echo ""
+echo "╔═══════════════════════════════════════════════════════════╗"
+echo "║          Flutter Test & Coverage Summary                 ║"
+echo "╠═══════════════════════════════════════════════════════════╣"
+echo "║ Package              Pass    Fail    Lines    Coverage   ║"
+echo "╠═══════════════════════════════════════════════════════════╣"
+
+TOTAL_PASS=0
+TOTAL_FAIL=0
+TOTAL_HIT=0
+TOTAL_FOUND=0
+
+for pkg in "${TESTABLE[@]}"; do
+  NAME=$(basename "$pkg")
+  P=${RESULTS_PASS[$NAME]:-0}
+  F=${RESULTS_FAIL[$NAME]:-0}
+  LH=${RESULTS_LH[$NAME]:-0}
+  LF=${RESULTS_LF[$NAME]:-0}
+  PCT=${RESULTS_PCT[$NAME]:-"—"}
+
+  if [ "$PCT" != "—" ]; then
+    LINES="$LH/$LF"
+    PCT_DISPLAY="${PCT}%"
+  else
+    LINES="—"
+    PCT_DISPLAY="—"
+  fi
+
+  printf "║ %-20s %-7s %-7s %-8s %-10s ║\n" "$NAME" "$P" "$F" "$LINES" "$PCT_DISPLAY"
+  TOTAL_PASS=$((TOTAL_PASS + P))
+  TOTAL_FAIL=$((TOTAL_FAIL + F))
+  TOTAL_HIT=$((TOTAL_HIT + LH))
+  TOTAL_FOUND=$((TOTAL_FOUND + LF))
+done
+
+if [ "$TOTAL_FOUND" -gt 0 ]; then
+  TOTAL_PCT=$(awk "BEGIN {printf \"%.1f\", ($TOTAL_HIT/$TOTAL_FOUND)*100}")
+  TOTAL_LINES="$TOTAL_HIT/$TOTAL_FOUND"
+  TOTAL_PCT_DISPLAY="${TOTAL_PCT}%"
+else
+  TOTAL_LINES="—"
+  TOTAL_PCT_DISPLAY="—"
+fi
+
+echo "╠═══════════════════════════════════════════════════════════╣"
+printf "║ %-20s %-7s %-7s %-8s %-10s ║\n" "TOTAL" "$TOTAL_PASS" "$TOTAL_FAIL" "$TOTAL_LINES" "$TOTAL_PCT_DISPLAY"
+echo "╚═══════════════════════════════════════════════════════════╝"
+
+if [ $OVERALL_EXIT -ne 0 ]; then
+  echo ""
+  echo "❌ Failures detected. See details above."
+else
+  echo ""
+  echo "✅ All $TOTAL_PASS tests passed across all packages."
+  echo "📊 Overall line coverage: $TOTAL_PCT_DISPLAY ($TOTAL_LINES lines)"
+fi
+
+exit $OVERALL_EXIT

kell_creations_apps/tools/run_all_tests.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────────────
+# run_all_tests.sh — Run flutter test for all testable packages and apps
+#
+# Usage:
+#   ./tools/run_all_tests.sh           # Run from kell_creations_apps/
+#   ./tools/run_all_tests.sh --analyze # Also run dart analyze first
+#
+# Exit codes:
+#   0 — all tests passed (and analyze clean, if requested)
+#   1 — one or more failures
+# ──────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Packages/apps with tests (add new ones here as they gain tests)
+TESTABLE=(
+  packages/core
+  packages/design_system
+  packages/feature_wordpress
+  apps/kell_web
+)
+
+# All packages/apps to analyze (includes those without tests)
+ANALYZABLE=(
+  packages/core
+  packages/design_system
+  packages/feature_wordpress
+  packages/feature_inventory
+  packages/feature_orders
+  packages/feature_policy
+  apps/kell_web
+  apps/kell_mobile
+)
+
+RUN_ANALYZE=false
+if [[ "${1:-}" == "--analyze" ]]; then
+  RUN_ANALYZE=true
+fi
+
+OVERALL_EXIT=0
+
+# ── Dependency install ───────────────────────────────────────────────
+echo ""
+echo "══════════════════════════════════════"
+echo "  Installing dependencies"
+echo "══════════════════════════════════════"
+
+for pkg in "${ANALYZABLE[@]}"; do
+  echo "  → $pkg"
+  (cd "$ROOT_DIR/$pkg" && flutter pub get --no-example) > /dev/null 2>&1
+done
+
+# ── Analyze (optional) ──────────────────────────────────────────────
+if $RUN_ANALYZE; then
+  echo ""
+  echo "══════════════════════════════════════"
+  echo "  Running dart analyze"
+  echo "══════════════════════════════════════"
+
+  ANALYZE_FAILURES=()
+  for pkg in "${ANALYZABLE[@]}"; do
+    NAME=$(basename "$pkg")
+    printf "  %-25s" "$NAME"
+    if (cd "$ROOT_DIR/$pkg" && dart analyze --fatal-infos) > /dev/null 2>&1; then
+      echo "✅ clean"
+    else
+      echo "❌ issues found"
+      ANALYZE_FAILURES+=("$NAME")
+      OVERALL_EXIT=1
+    fi
+  done
+
+  if [ ${#ANALYZE_FAILURES[@]} -gt 0 ]; then
+    echo ""
+    echo "  ❌ Analyze failures: ${ANALYZE_FAILURES[*]}"
+  else
+    echo ""
+    echo "  ✅ All packages analyze clean"
+  fi
+fi
+
+# ── Tests ────────────────────────────────────────────────────────────
+echo ""
+echo "══════════════════════════════════════"
+echo "  Running flutter test"
+echo "══════════════════════════════════════"
+
+declare -A RESULTS_PASS
+declare -A RESULTS_FAIL
+TEST_FAILURES=()
+
+for pkg in "${TESTABLE[@]}"; do
+  NAME=$(basename "$pkg")
+  echo ""
+  echo "  ── $NAME ──"
+
+  TMPFILE=$(mktemp)
+  if (cd "$ROOT_DIR/$pkg" && flutter test --reporter expanded 2>&1) | tee "$TMPFILE"; then
+    : # tests passed
+  else
+    TEST_FAILURES+=("$NAME")
+    OVERALL_EXIT=1
+  fi
+
+  PASS=$(grep -cE '^\s*✓' "$TMPFILE" 2>/dev/null || echo "0")
+  FAIL=$(grep -cE '^\s*✗' "$TMPFILE" 2>/dev/null || echo "0")
+  RESULTS_PASS[$NAME]=$PASS
+  RESULTS_FAIL[$NAME]=$FAIL
+  rm -f "$TMPFILE"
+done
+
+# ── Summary ──────────────────────────────────────────────────────────
+echo ""
+echo "╔══════════════════════════════════════╗"
+echo "║     Flutter Test Results Summary     ║"
+echo "╠══════════════════════════════════════╣"
+echo "║ Package              Pass    Fail    ║"
+echo "╠══════════════════════════════════════╣"
+
+TOTAL_PASS=0
+TOTAL_FAIL=0
+
+for pkg in "${TESTABLE[@]}"; do
+  NAME=$(basename "$pkg")
+  P=${RESULTS_PASS[$NAME]:-0}
+  F=${RESULTS_FAIL[$NAME]:-0}
+  printf "║ %-20s %-7s %-7s ║\n" "$NAME" "$P" "$F"
+  TOTAL_PASS=$((TOTAL_PASS + P))
+  TOTAL_FAIL=$((TOTAL_FAIL + F))
+done
+
+echo "╠══════════════════════════════════════╣"
+printf "║ %-20s %-7s %-7s ║\n" "TOTAL" "$TOTAL_PASS" "$TOTAL_FAIL"
+echo "╚══════════════════════════════════════╝"
+
+if [ $OVERALL_EXIT -ne 0 ]; then
+  echo ""
+  echo "❌ Failures detected. See details above."
+else
+  echo ""
+  echo "✅ All $TOTAL_PASS tests passed across all packages."
+fi
+
+exit $OVERALL_EXIT

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: