v0.1.4

Author: RichardGeorgeDavis

README.md

@@ -11,6 +11,7 @@ It combines:
 - a predictable folder layout for mixed stacks
 - shared caches and helper tooling
 - lightweight workspace metadata
+- a filesystem-first context model for docs, manifests, and agent guidance
 - a vendored [Workspace Hub](repos/workspace-hub/README.md) app for discovery, runtime control, and previews
 
 ## Why It Exists
@@ -23,6 +24,28 @@ This repo exists to keep local development practical when your machine contains
 - WordPress, Vite, static, PHP, and utility repos can coexist cleanly
 - ServBay remains optional rather than becoming a hard dependency
 
+## Challenges
+
+Mixed local workspaces tend to accumulate useful context in too many places at once:
+
+- repo docs and READMEs
+- runtime manifests and config files
+- screenshots and previews
+- local notes and operator overrides
+- repo-specific skills and machine-specific agent setup
+
+When that context is fragmented, tools and agents either miss important signals or pull in too much noise too early.
+
+## Our Approach
+
+Codex Workspace addresses that with a practical filesystem-first model:
+
+- keep repo facts in normal tracked files
+- keep generated summaries in `cache/`
+- keep reusable skills portable across agents
+- keep machine-specific memory and secrets local
+- keep retrieval and repo classification explainable
+
 ## Core Principles
 
 - Do not merge unrelated repos into one dependency structure.
@@ -32,6 +55,24 @@ This repo exists to keep local development practical when your machine contains
 - Keep WordPress handling pragmatic.
 - Use lightweight manifests where explicit runtime behaviour helps.
 
+## Core Concepts
+
+### Filesystem-shaped context
+
+Repo context should live in normal files and folders that are easy to inspect, not in hidden tool state.
+
+### Layered context loading
+
+Use short summaries first, then read deeper repo details only when needed.
+
+### Observable retrieval
+
+Repo classification and generated summaries should be explainable from the files that informed them.
+
+### Cautious memory
+
+Keep durable repo knowledge tracked. Keep operator memory, secrets, and machine-specific notes local until they prove broadly useful.
+
 ## Workspace Layout
 
 ```text
@@ -76,6 +117,7 @@ Start here:
 - [docs/04-build-order-and-dod.md](docs/04-build-order-and-dod.md)
 - [docs/05-examples-and-templates.md](docs/05-examples-and-templates.md)
 - [docs/06-cross-agent-skills-and-mcp.md](docs/06-cross-agent-skills-and-mcp.md)
+- [docs/07-context-cache-and-retrieval.md](docs/07-context-cache-and-retrieval.md)
 
 Supporting references:
 - [docs/HANDOVER.md](docs/HANDOVER.md)
@@ -92,6 +134,25 @@ See:
 - [repos/workspace-hub/docs/manifest.md](repos/workspace-hub/docs/manifest.md)
 - [repos/workspace-hub/docs/runtime-troubleshooting.md](repos/workspace-hub/docs/runtime-troubleshooting.md)
 
+## Context For Agents
+
+Codex Workspace treats agent-facing context as normal workspace content rather than a hidden prompt blob.
+
+The practical model is:
+
+- tracked resources such as repo docs, READMEs, and manifests
+- portable skills stored in workspace-wide or repo-local folders
+- generated context summaries under `cache/context/`
+- local-only memory and MCP config kept separate from tracked repo content
+
+This keeps context easier to inspect, reason about, and adapt across tools while keeping each repo independently runnable.
+
+Tracked repo knowledge belongs in public docs, manifests, and portable skills. Local operator memory belongs in ignored local files until it becomes stable enough to promote into tracked project guidance.
+
+See:
+- [docs/06-cross-agent-skills-and-mcp.md](docs/06-cross-agent-skills-and-mcp.md)
+- [docs/07-context-cache-and-retrieval.md](docs/07-context-cache-and-retrieval.md)
+
 ## Community
 
 - [LICENSE](LICENSE)

cover.png

@@ -16,6 +16,40 @@ The goal is to create a central workspace on the Mac desktop that:
 
 This pack is intentionally split into separate files so Codex can reason about architecture and runtime concerns clearly.
 
+## Context model
+
+The workspace also aims to keep agent-facing context explicit and inspectable.
+
+That means:
+
+- repo docs and manifests remain the primary source of truth
+- portable skills live in normal workspace folders
+- generated summaries belong under `cache/`
+- local-only memory and secrets stay local
+
+The intended result is a filesystem-first context model that is easier to inspect and less opaque than ad hoc prompt assembly.
+
+## Challenges
+
+Mixed-repo workspaces tend to fragment context across docs, manifests, runtime config, local notes, and tool-specific setup.
+
+That creates a few predictable problems:
+
+- useful repo knowledge becomes harder to find
+- too much detail gets loaded before relevance is established
+- local operator knowledge leaks into tracked docs
+- tool decisions become harder to explain
+
+## Approach
+
+Codex Workspace addresses that with a practical local-first model:
+
+- keep repo facts in tracked files
+- keep generated summaries in `cache/`
+- keep skills portable rather than vendor-locked
+- keep local operator memory separate from tracked project knowledge
+- keep classification and retrieval observable
+
 ## Files in this pack
 
 ### `01-codex-workspace-handover.md`
@@ -46,6 +80,11 @@ Each repository remains independently runnable in the way that best suits it:
 - Vite / Three.js / WebGL projects via their dev server
 - other stacks according to their own tooling
 
+The context model follows the same principle:
+- tracked repo resources are the canonical source of truth
+- generated summaries are helper layers
+- local memory is private until promoted intentionally
+
 ## Important architectural rule
 
 **Every repository must remain runnable without ServBay.**
@@ -86,10 +125,12 @@ This setup should optimise for:
 - clarity
 - speed
 - low duplication
+- observable context
 - predictable repo handling
 - compatibility with Codex
 - compatibility with mixed repo types
 - clean future expansion
+- debuggable agent and tooling behaviour
 
 ## Non-goals
 

docs/00-overview.md

@@ -53,6 +53,18 @@ Workspace Hub is:
 - a local orchestration layer
 - a visibility and convenience tool
 
+## Challenges
+
+In a mixed local workspace, the Hub needs to solve more than simple repo listing.
+
+It also needs to make sense of:
+
+- fragmented repo metadata
+- conservative type detection
+- multiple runtime models
+- generated summaries versus source-of-truth files
+- local-only operator knowledge that should not be mistaken for shared repo fact
+
 ## Recommended stack
 
 ### Current v1 stack
@@ -80,6 +92,7 @@ The Hub must be able to:
 - read key files from each repo
 - detect repo type
 - read optional repo manifest files
+- read cached repo context summaries when present
 - launch local commands
 - track running process state
 - stop launched processes
@@ -151,6 +164,7 @@ Each repo card or row should show:
 When a repo is selected, show:
 - summary metadata
 - detected files
+- context sources where available
 - commands
 - notes
 - current branch
@@ -189,6 +203,8 @@ Suggested detection signals:
 - lockfiles
 - known dependencies such as Three.js
 
+The Hub should retain enough evidence to explain its classification to the user.
+
 ### Repo manifest reading
 If `.workspace/project.json` exists in a repo, it should override or guide detected behaviour.
 
@@ -227,6 +243,33 @@ These are valuable and should be included if they do not slow down the first bui
 - lockfile/package manager detection
 - dependency missing warning
 - quick copy URL action
+- context cache freshness and provenance view
+
+## Context model
+
+Workspace Hub should treat repo context as a visible filesystem concern rather than an opaque internal prompt.
+
+In practice that means:
+
+- tracked docs and manifests are the source of truth
+- generated `L0` and `L1` summaries may live under `cache/context/`
+- raw repo files remain the `L2` detail layer
+- the Hub should be able to show which files informed a summary when that metadata exists
+
+This keeps classification and summary behaviour explainable and easier to debug.
+
+## Retrieval observability
+
+Workspace Hub should make retrieval and detection decisions visible where practical.
+
+Useful examples:
+
+- show which files drove repo classification
+- show which files were used to generate the current summary
+- show whether a summary is fresh or stale relative to its inputs
+- distinguish between tracked repo context and local-only operator overrides
+
+If the Hub says a repo is `vite`, the user should be able to see why.
 
 ## Data and persistence
 
@@ -248,6 +291,8 @@ Persist:
 
 Do not persist sensitive secrets in custom metadata files.
 
+Local-only operator notes may be persisted, but they should stay clearly separate from tracked repo metadata and should never silently overwrite published repo facts.
+
 ## Repo manifest schema
 
 Preferred path in each repo:

docs/03-workspace-hub-build-spec.md

@@ -110,6 +110,40 @@ Good contents:
 
 Do not store real secrets or machine-specific absolute paths here.
 
+## Tracked knowledge vs local memory
+
+Separate durable repo knowledge from operator memory.
+
+Tracked repo knowledge includes things such as:
+
+- repo runtime rules
+- stable troubleshooting notes
+- reusable workflow guidance
+- durable task instructions that other contributors should also see
+
+That knowledge should live in tracked files such as:
+
+- `README.md`
+- `docs/`
+- `.workspace/project.json`
+- `.workspace/skills/`
+
+Local operator memory includes things such as:
+
+- machine-specific paths
+- private MCP endpoints
+- temporary workarounds
+- personal notes and reminders
+- secrets or environment-specific preferences
+
+That material should stay in ignored local files by default.
+
+## Promotion rule
+
+If a local note proves stable, broadly useful, and safe to publish, promote it into tracked docs, manifests, or portable skills.
+
+Do not rely on private local memory as the long-term home of canonical repo knowledge.
+
 ## Adapter rule
 
 If an agent expects a specific directory such as `.agents/skills/` or `.claude/skills/`, create that as an adapter target, not as the primary source.
@@ -160,6 +194,7 @@ Avoid making Workspace Hub responsible for launching or orchestrating agent-spec
 - local secrets and machine paths last
 - repo opt-in, never mandatory
 - no agent setup should be required to run a repo normally
+- promote durable local knowledge into tracked files when it becomes generally useful
 
 ## Practical outcome