cox-protocol-package 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.2.0 — 2026-09-29
+
+- Ship canonical schemas and a complete starter inside the namespaced Python package; align Python, npm and VS Code versions.
+- Add `init`, `--json`, `--strict`, `--version` and `verify-package` CLI surfaces.
+- Reject ambiguous YAML, invalid project paths and inconsistent manifest/page/component bindings with structured diagnostics.
+- Support shared component folders within the project; prevent generated identifier and output-path collisions.
+- Preserve evidence in safely escaped React comments and validate generated scaffolds with TypeScript.
+- Stage builds before publication, track generated-file ownership, preserve unrelated files, refuse local-edit overwrites and remove only stale owned output.
+- Support external output directories and deterministic archives containing the current run's compiled manifest and reports; verify inventory hashes, sizes, paths and modes.
+- Reject non-portable filenames inside referenced source directories before packaging, and reject symlink metadata on every ZIP entry, including the inventory.
+- Add regression tests, clean-install release checks, CI and a reproducible failing/corrected contract demonstration.
+- Replace subjective readiness scores with explicit capability boundaries and verification evidence.
+
+### Migration
+
+COX format remains 1.0. Duplicate YAML keys, aliases, non-JSON YAML values, unknown evidence labels, unsafe paths and mismatched bindings now fail validation. Quote textual YAML boolean words and dates. Use a new output folder for old builds without an ownership marker. The installed Python module is `cox_protocol`; source-checkout `tools` entry points remain compatibility shims. React output remains structural scaffolding.
+
+## Earlier releases
+
+The baseline used Python 1.0.1, npm 1.0.2, and VS Code extension 1.1.0. It provided schema validation, JSON/React/package targets and syntax/snippet support. Historical intake notes remain under `guides/imported-packages/`.

package/COX_FILE_FORMAT_SPECIFICATION_v1.0.md

@@ -1,236 +1,76 @@
-# COX File Format Specification v1.0
+# COX file format 1.0
 
-## 1. Status
+This specification accompanies compiler 1.2.0. The executable field contract is defined by the five JSON Schemas in `schemas/`, mirrored in the installed `cox_protocol/schemas/` package.
 
-- Format name: `COX`
-- Version: `1.0`
-- File extension: `.cox`
-- MIME type: `application/vnd.cox+yaml`
-- Encoding: `UTF-8`
-- Syntax base: `YAML-compatible structured text`
-- Entry point: `manifest.cox`
+## Representation
 
-## 2. Purpose
+COX uses `.cox`, UTF-8, and the descriptive MIME type `application/vnd.cox+yaml`. Each project has one `manifest.cox` entry point. Documents are YAML mappings with JSON-compatible values: string keys; mappings; arrays; strings; booleans; finite numbers; null. Key order is not significant. Common headers should appear first for readability, but the parser does not require an order.
 
-COX is a structured file format for UI reconstruction, evidence tracking, component binding, implementation guidance, and agent-readable design specifications. A COX project is manifest-driven and intended to be both human-readable and machine-validatable.
-
-## 3. Common Header
-
-Every `.cox` document must begin with the following versioned metadata header:
+The implementation uses PyYAML's safe scalar resolution. Quote version strings, dates, and textual YAML boolean words such as `Yes`, `No`, `on`, and `off`. Duplicate keys, aliases (including merge aliases), non-string keys, YAML-specific object types, timestamps and non-finite numbers are rejected. Unsupported custom tags are rejected. Anchors without references add no semantics. One document per file is supported.
 
 ```yaml
 CoxVersion: "1.0"
 FileType: "component_spec"
-Slug: "projects_grid_cards"
+Slug: "action_button"
 Schema: "cox.component.v1"
 ```
 
-Required header fields for all COX documents:
-
-- `CoxVersion`
-- `FileType`
-- `Slug`
-- `Schema`
-
-## 4. Supported File Types
-
-### `manifest`
-
-Project entrypoint that defines the package contract, referenced pages, guide documents, protocol documents, skill bundles, schemas, tooling, and build targets.
-
-Required top-level fields:
-
-- `CoxVersion`
-- `FileType`
-- `Slug`
-- `Schema`
-- `ProjectName`
-- `ProtocolExtension`
-- `MimeType`
-- `EntryPoint`
-- `Pages`
-
-Optional manifest file collections:
-
-- `ReferenceDocs`: human-facing root documentation files
-- `GuideDocs`: guide or tutorial files imported into `guides/`
-- `ProtocolDocs`: `.cox` methodology and system protocol documents
-- `SkillBundles`: LLM-agent skill bundle files or directories imported into `skills/`
-- `Schemas`: JSON Schema files used by the validator
-- `ToolingFiles`: compiler, editor, package, and distribution tooling files
-
-Supported build targets:
-
-- `json`
-- `react`
-- `package`
-
-### `page_spec`
-
-Defines page-level evidence, visible regions, child component bindings, layout behavior, and page interactions.
-
-Required top-level fields:
-
-- `CoxVersion`
-- `FileType`
-- `PageName`
-- `Slug`
-- `Schema`
-- `ProjectName`
-- `EvidenceSummary`
-- `VisibleStructure`
-- `Interactions`
-
-### `component_spec`
-
-Defines a reusable UI component, its evidence basis, visible structure, visual style, and interactions.
-
-Required top-level fields:
-
-- `CoxVersion`
-- `FileType`
-- `ComponentName`
-- `Slug`
-- `Schema`
-- `EvidenceSummary`
-- `VisibleStructure`
-- `Interactions`
-
-### `protocol_doc`
-
-Defines COX process rules, naming conventions, orchestration rules, logic notes, design tokens, or validation checklists.
-
-Required top-level fields:
-
-- `CoxVersion`
-- `FileType`
-- `Slug`
-- `Schema`
-- `ProtocolName`
-- `Purpose`
-
-### `crop_metadata`
-
-Defines crop planning metadata for derived screenshots.
-
-Required top-level fields:
-
-- `CoxVersion`
-- `FileType`
-- `Slug`
-- `Schema`
-- `SourceScreenshot`
-- `OutputScreenshot`
-- `BoundaryConfidence`
-- `EstimatedBoundingBox`
-
-## 5. Slug Rules
-
-`Slug` values use lowercase snake case.
-
-Allowed pattern:
-
-```text
-^[a-z0-9]+(_[a-z0-9]+)*$
-```
-
-Examples:
-
-- `dashboard`
-- `projects_grid_cards`
-- `deterministic_naming_convention`
+All documents require these four fields. `CoxVersion` must be the string `1.0`. Slugs match `^[a-z0-9]+(_[a-z0-9]+)*$`. A document's `FileType` and `Schema` must correspond exactly.
 
-## 6. Evidence Model
+## Document types
 
-When evidence is relevant, COX documents should separate claims into explicit evidence levels:
+The following required fields are **in addition to the four common fields**. See the schemas for nested requirements, enums and optional fields.
 
-- `Visible`
-- `UserSpecified`
-- `Inferred`
-- `Intended`
-- `Recommended`
+| FileType | Schema | Additional required fields |
+|---|---|---|
+| manifest | cox.manifest.v1 | ProjectName, ProtocolExtension, MimeType, EntryPoint, Pages |
+| page_spec | cox.page.v1 | PageName, ProjectName, EvidenceSummary, VisibleStructure, Interactions, NamingDecision, Layout, Children, RecursiveDecompositionDecision |
+| component_spec | cox.component.v1 | ComponentName, Role, EvidenceSummary, VisibleStructure, Interactions, NamingDecision |
+| protocol_doc | cox.protocol.v1 | ProtocolName, Purpose |
+| crop_metadata | cox.crop_metadata.v1 | SourceScreenshot, OutputScreenshot, BoundaryConfidence, EstimatedBoundingBox |
 
-The format does not permit inferred behavior to be represented as certain without explicit visible or user-provided evidence.
+A manifest requires at least one page. `ProtocolExtension`, `MimeType`, and `EntryPoint` use the fixed values `.cox`, `application/vnd.cox+yaml`, and `manifest.cox`. Every page entry includes `PageName`, `Slug`, `Folder`, `PageInstruction`, `PageScreenshotPlaceholder`, and `Components`. Component entries include `Slug`, `Folder`, `ComponentInstruction`, and `ComponentScreenshotPlaceholder`. Empty component arrays are permitted.
 
-## 7. Validation Model
+`NamingDecision` records ChosenName, Reason, RejectedAlternatives, AmbiguityRisk, and EvidenceLevel. Layout requires Desktop, Tablet, and Mobile strings. COX v1 permits extensible prose fields in several objects; passing schema validation does not make those fields executable.
 
-COX documents are parsed as YAML and validated against JSON Schema Draft 2020-12.
+## Evidence
 
-Canonical schema ids:
+`EvidenceSummary` and `Interactions` accept the five evidence labels `Visible`, `UserSpecified`, `Inferred`, `Intended`, and `Recommended`, each an array of strings. Unknown labels are rejected. A naming decision's EvidenceLevel must use the same vocabulary. These categories distinguish observation, supplied requirements, interpretation, desired behavior, and suggestions.
 
-- `cox.manifest.v1`
-- `cox.page.v1`
-- `cox.component.v1`
-- `cox.protocol.v1`
-- `cox.crop_metadata.v1`
+The tool checks the representation and vocabulary, not whether an observation is true. Screenshot placeholders and generated reference illustrations must be described honestly. Crop metadata is a planning document: screenshot strings and bounding-box descriptions are not a pixel-analysis or file-existence guarantee.
 
-Validation must include:
+## References and bindings
 
-- UTF-8 decoding
-- YAML parsing
-- Schema validation
-- Manifest reference existence checks
-- Page/component path checks
-- Unreferenced `.cox` file detection as a warning
+Manifest paths are relative POSIX paths within the project. Absolute paths, backslashes, parent traversal and symlink references are rejected. Referenced inputs must exist. Page/component instructions and their screenshot/placeholder files must be regular files inside the corresponding Folder. Instruction files use `.cox`.
 
-## 8. Compilation Model
+The page document's Slug, PageName and ProjectName must match its manifest entry and project. Page slugs are unique. A component document's Slug must match its manifest binding. A shared component slug may be reused when it names the same source; different source files may not claim the same component slug.
 
-The first professional compilation target for COX v1.0 is normalized JSON. The current compiler also supports React stubs and deterministic package ZIP output.
+`Children.Components` must match that page's manifest component set, without duplicates. Each child's Folder is relative to the page instruction's directory. It may use `..` to reach a shared component **within** the project; it cannot escape the project or traverse symlinks.
 
-Expected pipeline:
+Optional input collections are ReferenceDocs, GuideDocs, ProtocolDocs, SkillBundles, Schemas and ToolingFiles. ProtocolDocs must contain protocol document files. Referenced `.cox` files under GuideDocs and SkillBundles are also validated. Other collections include assets/documentation without interpreting arbitrary files as COX. The compiler always uses its installed canonical schemas; the Schemas collection packages supporting files and cannot override validation rules.
 
-```text
-.cox files
-  -> parse YAML
-  -> validate against schema
-  -> check references and paths
-  -> emit normalized JSON
-  -> generate verification report
-```
+Unreferenced `.cox` files produce a warning; `--strict` makes that warning an error. Nested independent projects, managed build outputs and transient directories are excluded from this scan. `VerificationRules` and protocol text are guidance, not dynamically executed code.
 
-Recommended commands:
+## Compilation
 
-```bash
-cox validate ./cox_protocol_package
-cox compile ./cox_protocol_package --out ./build
-cox compile ./cox_protocol_package --target react --out ./build
-cox compile ./cox_protocol_package --target json --target react --target package --out ./build
-```
+Validation precedes every build. CLI targets are `json`, `react`, `package`, and `all`. Repeated/comma-separated target arguments are normalized into stable order. Without a target the compiler emits JSON. Manifest BuildTargets is descriptive project metadata.
 
-Expected build outputs:
-
-```text
-build/
-  manifest.compiled.json
-  normalized/
-  package/
-    cox_protocol_package_corrected.zip
-    cox_protocol_package_corrected.manifest.json
-  reports/
-    verification_report.txt
-```
+- **JSON:** normalized documents preserving data and evidence; compiled manifest records relative input/output paths.
+- **React:** typed TSX page/component scaffolds with source evidence comments. Snake-case slugs become PascalCase; numeric starts receive `Cox`. Conflicting generated symbols are errors. ProjectName must be a portable single directory name. Prose is safely escaped. No finished CSS, event behavior, data fetching, AST conformance or rendered compliance is inferred.
+- **Package:** a single-root ZIP named by PackageName or Slug. The root is the manifest slug, independent of checkout location. It contains declared sources and only artifacts from this invocation, including the compiled manifest and verification report.
 
-Optional React stub output:
-
-```text
-build/
-  react/
-    components/
-    pages/
-    index.ts
-    manifest.react.json
-```
+Relative output paths are relative to the discovered project. Absolute external outputs are supported. Output parents are canonicalized, including standard OS temporary-directory aliases. The output directory itself and managed paths within it may not be symlinks. Canonical output paths may not overlap source inputs, the project root or an ancestor. Builds stage independently and publish only owned files; `.cox-build.json` records their exact hashes. Unknown collisions and human-modified artifacts are preserved with a diagnostic. A target removed from the command removes only its prior owned files.
 
-The `react` target consumes the same normalized COX document model used by the JSON target and emits framework-neutral TSX stubs. COX v1.0 does not require the compiler to infer concrete CSS values or executable interaction logic from prose-only layout and evidence sections.
+## Archive contract
 
-The `package` target emits a deterministic ZIP archive from manifest-referenced source files and any generated outputs produced earlier in the same compilation pass. Package archives must use project-relative paths under a single archive root, sorted file ordering, fixed ZIP timestamps, and SHA-256 records for every packaged file. Local caches, virtual environments, raw intake ZIPs, and package output directories must not be included.
+Names are sorted, timestamps fixed at 1980-01-01, permissions normalized to 0644 (or 0755 for executable source files), and archive paths use POSIX separators. Cache/build directories, Python bytecode, environment files and identified historical raw intake archives are excluded. Explicit references to excluded inputs fail packaging.
 
-Guide and skill bundle intake is intentionally explicit. The compiler supports `GuideDocs` and `SkillBundles`, but ZIP attachments must be inspected and curated before their paths are added to the manifest.
+The embedded `package.manifest.json` inventories payload entries with path, source, kind, size, SHA-256 and mode. It excludes itself to avoid a self-referential hash. `fileCount` counts those payload entries; the ZIP has one additional inventory entry. An external `.manifest.json` additionally records the complete ZIP's size and SHA-256. The ZIP does not contain itself or this external inventory.
 
-## 9. Editor Support
+`cox verify-package` checks entry uniqueness, portable paths, a single root inventory, exact inventory coverage, sizes, hashes, permissions and absence of symlink entries. It does not establish author identity or protect against an attacker replacing both files and the inventory. Verify a trusted external checksum when provenance matters. Byte-for-byte reproducibility is scoped to identical input bytes/modes and compression toolchain.
 
-COX editor support should register `.cox` as its own language id and may initially inherit YAML-compatible tokenization. Header keys such as `CoxVersion`, `FileType`, `Slug`, and `Schema` should be highlighted distinctly.
+## Errors and compatibility
 
-## 10. Compatibility
+Commands support `--json`, returning `ok` and either result fields or `errors` with code, message, path and location. Invalid contracts/builds/archives exit 1. CLI usage errors exit 2 with the normal argument-parser message. `--strict` is supported for validation and compilation.
 
-COX v1.0 is compatible with YAML tooling that preserves mappings, lists, strings, and nested objects. COX-specific validity is determined by COX schemas rather than YAML parsing alone.
+Tool versions and file-format versions are independent. Compiler 1.2.0 strengthens diagnostics and rejects previously ambiguous input (duplicate keys, aliases, schema-label typos, inconsistent bindings and unsafe paths). Existing valid format-1.0 projects remain supported. Legacy generated folders without `.cox-build.json` should be rebuilt into a fresh directory. The npm wrapper invokes Python; it is not an independent TypeScript implementation. The VS Code extension provides syntax and snippets, with validation through the CLI.

package/FINALIZATION.md

@@ -0,0 +1,50 @@
+# COX finalisation acceptance record
+
+Objective: fully finalise the existing COX v1 format and its validator/compiler product, including its distributable tools and an inspectable demonstration. The format remains a structured UI/evidence contract; React output is deliberately structural scaffolding, as specified, rather than an inferred finished application.
+
+## Requirements and proof
+
+- [x] Canonical v1 schemas ship with an installed Python package and npm distribution; ordinary projects do not need a copy of the compiler repository.
+- [x] All five document types validate; malformed UTF-8/YAML, duplicate keys, unsupported schemas/versions, broken references and inconsistent page/component bindings produce actionable errors without tracebacks.
+- [x] Project-relative paths, source/output separation and generated code identifiers are checked; invalid inputs cannot escape the project/output root or silently overwrite another component.
+- [x] JSON and React targets produce deterministic, valid outputs; React scaffolds compile with TypeScript and preserve evidence as explanatory comments.
+- [x] Package target includes precisely this run's sources/artifacts with stable ordering/timestamps/permissions and verified SHA-256 records; external output directories work; stale outputs and unrelated files are not incorporated.
+- [x] Recompilation safely replaces only tool-owned outputs and never destroys unrelated user files.
+- [x] Fresh-project onboarding, human and JSON diagnostics, strict-warning mode and version reporting work through both Python and npm CLIs.
+- [x] A small invalid → diagnostic → corrected → compiled fixture demonstrates the real contract, with a reproducible verification command and honest capability boundaries.
+- [x] Python wheel/sdist, npm tarball and VS Code extension package cleanly; fresh isolated installs work away from this checkout. Versions, dependency requirements, metadata, schemas and snippets agree.
+- [x] Automated regression/integration checks and CI cover the format, compiler, packaging and fresh-install paths. Documentation commands are exercised.
+- [x] Release notes, installation guide, format specification, example guide, checksums and a final evidence report are complete. Public release status is explicitly recorded rather than assumed.
+
+## Initial evidence
+
+- Baseline: commit `e5d616c`, matching remote `main`; work continues on `codex/cox-protocol-finalisation`.
+- Pre-existing untracked `build/package/` is preserved.
+- Baseline `python3 -m tools.cox_cli validate .` passes 17 documents, but reports CLI 1.0.1 while npm metadata says 1.0.2.
+- No automated tests or CI are present in the baseline.
+- Initial inspection found schema resources are not included in the Python distribution; malformed manifests are indexed before validation errors are handled; package output outside the source root fails; stale generated directories can enter archives; React output accepts unchecked names/content.
+
+Completion requires checking every item above against the final current state. A successful baseline sample or a package build alone is insufficient.
+
+## Release verification — 29 September 2026
+
+- 58 regression/integration tests pass on Python 3.9.6 and Python 3.12.14 using separately installed runtime dependencies. Generated TSX passes TypeScript 7.0.2 with React 19.3.0 types. Node 25.9.0 exercised the wrapper and packaging locally.
+- Wheel installed in an isolated Python 3.9 environment; source distribution built and installed in an isolated Python 3.12 environment with an explicit preinstalled build backend. Both pass init, strict validation, invalid binding diagnostics, correction, all-target external compilation and ZIP verification away from the checkout.
+- npm tarball installs into a local prefix; its bundled root project validates all 17 documents with zero warnings. The final tarball is checked again through the installed wrapper.
+- COX Language Support 1.2.0 artifacts package successfully; all complete-document snippet expansions validate against the canonical schemas. Installation is checked in a separate VS Code data/extension directory.
+- The full repository sample compiles to JSON, React and package targets. The generated archive verifies. Tests compare byte-identical builds across two checkout and output locations and exercise modification, collision, stale-file, traversal, symlink, archive-tamper and rollback paths.
+- Static Python error/unused-import checks and Git whitespace checks pass. CI covers Python 3.9/3.12/3.14 with Node 22/24, separate wheel/sdist installs and npm/VSIX packaging. CI execution is tracked separately in the pull request; local checks do not establish a remote CI result.
+- The baseline's tracked generated build artifacts are removed from version control and ignored. Existing local build files, including the pre-existing untracked package directory, are preserved.
+
+## Distribution status and scope
+
+Release 1.2.0 is prepared as local wheel, sdist, npm tarball and VSIX artifacts with a developer handoff, reproducible demo and checksums. This task has not published to npm, PyPI or the VS Code Marketplace. Registry publication and merging the review branch are separate release actions. Artifact checksums and the final source revision belong in the external handoff record so they cannot create self-referential archive hashes.
+
+The completed scope is the COX v1 design-contract toolchain. React remains typed structural scaffolding. Arbitrary prose rules, rendered UI checks, AST conformance, MCP integration and adoption claims are outside the implemented product. No Windows execution or visual editor interaction is claimed by this local verification. Two upstream Typer/Click deprecation warnings appeared on Python 3.12; all checks passed.
+
+## Pre-merge packaging review — 18 October 2026
+
+- Directory references now reject non-portable descendant filenames before publishing outputs, so compilation cannot emit an archive that its own path verifier rejects.
+- ZIP symlink checks now cover every entry, including the embedded inventory rather than only inventoried payload files.
+- Six added regression cases cover these paths and bring the suite to 64 tests. The existing CI matrix continues to require generated TypeScript, isolated installs and all four distribution formats for the revised source.
+- Registry publication remains a separate action and is outside this review.

package/LocalAppManager/Dashboard/analytics_sidebar_panels/analytics_sidebar_panels.cox

@@ -0,0 +1,56 @@
+CoxVersion: "1.0"
+FileType: "component_spec"
+ComponentName: "analytics_sidebar_panels"
+Slug: "analytics_sidebar_panels"
+Schema: "cox.component.v1"
+Role: "Right-side analytics and status panels"
+EvidenceSummary:
+  Visible: []
+  UserSpecified:
+    - "Component name appears in the approved COX naming examples or derived example structure."
+  Inferred:
+    - "Detailed behavior should be adapted to actual screenshots when supplied."
+  Intended: []
+  Recommended: []
+
+NamingDecision:
+  ChosenName: "analytics_sidebar_panels"
+  Reason: "Clear domain + location + component group."
+  RejectedAlternatives:
+    - "generic_section"
+    - "nested_panel"
+    - "ambiguous_area"
+  AmbiguityRisk: "Low"
+  EvidenceLevel: "UserSpecified"
+
+VisibleStructure:
+  Note: "Placeholder until real screenshot crop is supplied."
+  ExpectedRegions:
+    - "Container surface"
+    - "Primary content group"
+    - "Secondary controls or metadata where visible"
+
+VisualStyle:
+  Tokens:
+    - "Color.SurfaceGlass"
+    - "Shape.CardRadius"
+    - "Typography.Body"
+    - "Motion.General"
+
+Interactions:
+  Visible: []
+  Inferred:
+    - "Hover and selected states may be required if controls are interactive."
+  Intended: []
+  Recommended:
+    - "Add keyboard-focus states and accessible labels."
+
+Responsive:
+  Desktop: "Use page-level placement."
+  Tablet: "Compress spacing and preserve hierarchy."
+  Mobile: "Stack or collapse only if layout requires it."
+
+ImplementationHints:
+  - "Implement as reusable component mapped to this exact slug."
+  - "Do not rename without updating protocols/component_binding_graph.cox and manifest.cox."
+ChildSubcomponents: []

package/LocalAppManager/Dashboard/analytics_sidebar_panels/analytics_sidebar_panels_screenshot.placeholder.txt

@@ -0,0 +1 @@
+Replace this placeholder with analytics_sidebar_panels_screenshot.png after real screenshot partitioning.

package/LocalAppManager/Dashboard/dashboard.cox

@@ -0,0 +1,62 @@
+CoxVersion: "1.0"
+FileType: "page_spec"
+PageName: "Dashboard"
+Slug: "dashboard"
+Schema: "cox.page.v1"
+ProjectName: "LocalAppManager"
+PageType: "dashboard_overview"
+EvidenceSummary:
+  Visible: []
+  UserSpecified:
+    - "Example directory organization uses LocalAppManager and Dashboard."
+    - "Component examples include projects_grid_cards and left_navigation_sidebar."
+  Inferred:
+    - "Dashboard may include sidebar, header, project grid, and analytics rail."
+  Intended: []
+  Recommended: []
+VisibleStructure:
+  Regions:
+    - "left_navigation_sidebar"
+    - "top_header_stats_bar"
+    - "projects_grid_cards"
+    - "analytics_sidebar_panels"
+
+NamingDecision:
+  ChosenName: "Dashboard"
+  Reason: "User-provided page name and common page-level role."
+  RejectedAlternatives: ["Overview", "Home", "Projects"]
+  AmbiguityRisk: "Low"
+  EvidenceLevel: "UserSpecified"
+
+Layout:
+  Desktop: "App shell with left navigation, top header/stats bar, central projects grid, optional right analytics rail."
+  Tablet: "Collapse analytics rail below main content or into tabbed panel."
+  Mobile: "Stack header, filters, project cards, and analytics sections vertically."
+
+Children:
+  Components:
+    - Slug: "left_navigation_sidebar"
+      Folder: "left_navigation_sidebar/"
+      Role: "Navigation and workspace filtering"
+    - Slug: "top_header_stats_bar"
+      Folder: "top_header_stats_bar/"
+      Role: "Page title, search/actions, KPI summaries"
+    - Slug: "projects_grid_cards"
+      Folder: "projects_grid_cards/"
+      Role: "Primary project discovery and launch grid"
+    - Slug: "analytics_sidebar_panels"
+      Folder: "analytics_sidebar_panels/"
+      Role: "Activity, usage, health, and chart summaries"
+
+Interactions:
+  Visible: []
+  Inferred:
+    - "Users likely navigate between shell regions, search/filter projects, and inspect analytics summaries."
+  Intended: []
+  Recommended:
+    - "Preserve keyboard navigation across dashboard regions and child component focus targets."
+
+RecursiveDecompositionDecision:
+  Complexity: "ComplexPage"
+  Reason: "Dashboard contains multiple distinguishable regions and likely interaction groups."
+  Action: "Use dashboard.cox for the page shell and child component .cox files for implementation details."

package/LocalAppManager/Dashboard/dashboard_screenshot.placeholder.txt

@@ -0,0 +1 @@
+Replace this placeholder with dashboard_screenshot.png after a real Dashboard screenshot is supplied.

package/LocalAppManager/Dashboard/left_navigation_sidebar/left_navigation_sidebar.cox

@@ -0,0 +1,56 @@
+CoxVersion: "1.0"
+FileType: "component_spec"
+ComponentName: "left_navigation_sidebar"
+Slug: "left_navigation_sidebar"
+Schema: "cox.component.v1"
+Role: "Global navigation, tags, and user/workspace controls"
+EvidenceSummary:
+  Visible: []
+  UserSpecified:
+    - "Component name appears in the approved COX naming examples or derived example structure."
+  Inferred:
+    - "Detailed behavior should be adapted to actual screenshots when supplied."
+  Intended: []
+  Recommended: []
+
+NamingDecision:
+  ChosenName: "left_navigation_sidebar"
+  Reason: "Clear left-side navigation role; avoids ambiguous left_sidebar."
+  RejectedAlternatives:
+    - "generic_section"
+    - "nested_panel"
+    - "ambiguous_area"
+  AmbiguityRisk: "Low"
+  EvidenceLevel: "UserSpecified"
+
+VisibleStructure:
+  Note: "Placeholder until real screenshot crop is supplied."
+  ExpectedRegions:
+    - "Container surface"
+    - "Primary content group"
+    - "Secondary controls or metadata where visible"
+
+VisualStyle:
+  Tokens:
+    - "Color.SurfaceGlass"
+    - "Shape.CardRadius"
+    - "Typography.Body"
+    - "Motion.General"
+
+Interactions:
+  Visible: []
+  Inferred:
+    - "Hover and selected states may be required if controls are interactive."
+  Intended: []
+  Recommended:
+    - "Add keyboard-focus states and accessible labels."
+
+Responsive:
+  Desktop: "Use page-level placement."
+  Tablet: "Compress spacing and preserve hierarchy."
+  Mobile: "Stack or collapse only if layout requires it."
+
+ImplementationHints:
+  - "Implement as reusable component mapped to this exact slug."
+  - "Do not rename without updating protocols/component_binding_graph.cox and manifest.cox."
+ChildSubcomponents: []

package/LocalAppManager/Dashboard/left_navigation_sidebar/left_navigation_sidebar_screenshot.placeholder.txt

@@ -0,0 +1 @@
+Replace this placeholder with left_navigation_sidebar_screenshot.png after real screenshot partitioning.

package/LocalAppManager/Dashboard/projects_grid_cards/projects_grid_cards.cox

@@ -0,0 +1,56 @@
+CoxVersion: "1.0"
+FileType: "component_spec"
+ComponentName: "projects_grid_cards"
+Slug: "projects_grid_cards"
+Schema: "cox.component.v1"
+Role: "Project cards grid for browsing, sorting, and launching local projects"
+EvidenceSummary:
+  Visible: []
+  UserSpecified:
+    - "Component name appears in the approved COX naming examples or derived example structure."
+  Inferred:
+    - "Detailed behavior should be adapted to actual screenshots when supplied."
+  Intended: []
+  Recommended: []
+
+NamingDecision:
+  ChosenName: "projects_grid_cards"
+  Reason: "Clear domain + layout + component type."
+  RejectedAlternatives:
+    - "generic_section"
+    - "nested_panel"
+    - "ambiguous_area"
+  AmbiguityRisk: "Low"
+  EvidenceLevel: "UserSpecified"
+
+VisibleStructure:
+  Note: "Placeholder until real screenshot crop is supplied."
+  ExpectedRegions:
+    - "Container surface"
+    - "Primary content group"
+    - "Secondary controls or metadata where visible"
+
+VisualStyle:
+  Tokens:
+    - "Color.SurfaceGlass"
+    - "Shape.CardRadius"
+    - "Typography.Body"
+    - "Motion.General"
+
+Interactions:
+  Visible: []
+  Inferred:
+    - "Hover and selected states may be required if controls are interactive."
+  Intended: []
+  Recommended:
+    - "Add keyboard-focus states and accessible labels."
+
+Responsive:
+  Desktop: "Use page-level placement."
+  Tablet: "Compress spacing and preserve hierarchy."
+  Mobile: "Stack or collapse only if layout requires it."
+
+ImplementationHints:
+  - "Implement as reusable component mapped to this exact slug."
+  - "Do not rename without updating protocols/component_binding_graph.cox and manifest.cox."
+ChildSubcomponents: []

package/LocalAppManager/Dashboard/projects_grid_cards/projects_grid_cards_screenshot.placeholder.txt

@@ -0,0 +1 @@
+Replace this placeholder with projects_grid_cards_screenshot.png after real screenshot partitioning.