Release v1.2.1 with AI side-load cache and handover automation

Author: RichardGeorgeDavis

AGENTS.md

@@ -140,6 +140,20 @@ When a user asks to update the workspace's reviewed GitHub refs or managed upstr
 
 Do not refresh those sources by hand when the wrapper already covers them.
 
+## Handover closeout
+
+When a user asks for a handover update, treat that as a memory-closeout request too.
+
+Default behavior:
+
+- if the handover update is repo-specific, run `tools/bin/workspace-memory save-repo <repo-name>` after the docs update
+- if the handover update is workspace-level, docs-level, or release-level, run `tools/bin/workspace-memory save-workspace` after the docs update
+- if both repo and workspace handover surfaces changed in one slice, run the closeout commands serially rather than in parallel
+- run a quick `git status` sanity check before closing the chat so the handover does not imply a cleaner worktree than actually exists
+- if public docs changed, confirm the public surfaces stay aligned: `README.md`, `docs/README.md`, `docs/CHANGELOG.md`, and the relevant repo-local README when one exists
+
+Do not leave MemPalace closeout as a manual reminder when the user explicitly asked for a handover update.
+
 ## New repo baseline
 
 When a repo is first added under `repos/`, assume the baseline in `docs/09-new-repo-baseline.md` applies unless that repo already has clearer local instructions.

README.md

@@ -56,6 +56,7 @@ If you want the fuller workspace path after that:
 
 - Start with [docs/08-first-run-and-updates.md](docs/08-first-run-and-updates.md).
 - Use [docs/README.md](docs/README.md) for the detailed docs index.
+- Use [docs/20-ai-context-side-load.md](docs/20-ai-context-side-load.md) for the generated AI side-load contract and the `generate-context-cache.sh` workflow.
 - Use [docs/09-new-repo-baseline.md](docs/09-new-repo-baseline.md) when adding or onboarding a repo.
 
 ## How To Contribute
@@ -173,6 +174,7 @@ Deeper docs:
 - [docs/11-core-memory-and-reference-promotion.md](docs/11-core-memory-and-reference-promotion.md)
 - [docs/18-mcp-server-catalog.md](docs/18-mcp-server-catalog.md)
 - [docs/19-mcp-authoring-rules.md](docs/19-mcp-authoring-rules.md)
+- [docs/20-ai-context-side-load.md](docs/20-ai-context-side-load.md)
 
 Supporting references:
 - [docs/HANDOVER.md](docs/HANDOVER.md)
@@ -200,6 +202,8 @@ The practical model is:
 - local-only memory and MCP config kept separate from tracked repo content
 - a small official MCP v1 profile set for Codex, installed through workspace-owned scripts instead of ad hoc one-off setup
 
+Side-load summaries are now generated with `tools/scripts/generate-context-cache.sh` into ignored `cache/context/workspace/` and `cache/context/repos/` paths. They are optional `L0` and `L1` cache files, not canonical workspace documentation.
+
 The current MCP v1 support set is intentionally small: OpenAI Docs, Context7, Playwright, Chrome DevTools, and GitHub.
 
 This keeps context easier to inspect, reason about, and adapt across tools while keeping each repo independently runnable.

docs/07-context-cache-and-retrieval.md

@@ -239,6 +239,8 @@ For future long-running agent jobs, a similar compact summary file under `cache/
 
 Use `tools/scripts/init-agent-job-bundle.sh` to create this local cache bundle when the work is large enough to justify it.
 
+Concrete side-load generation rules, source sets, and freshness semantics now live in [20-ai-context-side-load.md](20-ai-context-side-load.md).
+
 ### `plan.md` and `summary.md`
 
 These are job-level working files rather than canonical repo docs.
@@ -270,18 +272,40 @@ Suggested fields:
 ```json
 {
   "version": 1,
-  "generatedAt": "2026-03-21T10:30:00Z",
-  "repoRoot": "/absolute/path/to/repo",
+  "scope": "repo",
+  "target": "workspace-hub",
+  "generatedAt": "2026-04-10T10:30:00Z",
+  "generator": {
+    "path": "tools/scripts/generate-context-cache.sh"
+  },
   "inputs": [
     {
       "path": "README.md",
-      "kind": "readme",
-      "mtime": "2026-03-20T13:00:00Z"
+      "role": "repo-readme",
+      "bytes": 2048,
+      "mtimeMs": 1775816400000.0,
+      "sha256": "..."
     },
     {
       "path": ".workspace/project.json",
-      "kind": "manifest",
-      "mtime": "2026-03-20T13:05:00Z"
+      "role": "repo-manifest",
+      "bytes": 512,
+      "mtimeMs": 1775816700000.0,
+      "sha256": "..."
+    }
+  ],
+  "outputs": [
+    {
+      "path": "cache/context/repos/workspace-hub/abstract.md",
+      "role": "abstract"
+    },
+    {
+      "path": "cache/context/repos/workspace-hub/overview.md",
+      "role": "overview"
+    },
+    {
+      "path": "cache/context/repos/workspace-hub/sources.json",
+      "role": "sources"
     }
   ]
 }
@@ -355,10 +379,12 @@ For Workspace Hub, the relevant near-term use is modest:
 
 - detect whether context cache files exist
 - show whether summaries are fresh or stale
-- link to the source files behind a summary
+- link to generated summary files and tracked provenance
 - use cached `L0` and `L1` summaries to reduce repeated full-repo reads
 - explain which files and signals drove repo classification when available
 
+Agent-job bundles under `cache/context/agents/jobs/` stay separate from repo and workspace side-load summaries. They are local task artifacts, not the repo-level side-load cache.
+
 Good future enhancements:
 
 - regenerate summaries on demand

docs/08-first-run-and-updates.md

@@ -41,6 +41,22 @@ Then, once the app is open:
 
 If that trial path is enough, stop there and keep the rest of this doc as optional setup and maintenance guidance.
 
+## Fresh chat handover
+
+If you are starting a fresh repo-aware chat and want a cheaper wake-up path, use this sequence:
+
+1. read `docs/HANDOVER.md` and the directly relevant tracked README or doc first
+2. optionally refresh side-load summaries:
+   `tools/scripts/generate-context-cache.sh --workspace --run`
+3. for `workspace-hub` work, also run:
+   `tools/scripts/generate-context-cache.sh --repo workspace-hub --run`
+4. treat generated files under `cache/context/` as compact `L0` and `L1` summaries only
+5. trust tracked docs, manifests, and repo files over generated summaries whenever they differ
+
+Suggested instruction for a fresh chat:
+
+> Read `docs/HANDOVER.md` first. Use generated side-load files under `cache/context/` only as a compact summary layer, and treat tracked docs and repo files as canonical.
+
 ## Optional first-run questions
 
 Answer these in order:

docs/14-git-and-github-workflow.md

@@ -83,6 +83,10 @@ These names are guidance, not enforcement.
 - Use non-closing references such as `Refs #123` when the issue lives in another repo, when the PR targets a fork first, or when more work remains.
 - Close the issue when the accepted change actually lands, not when a branch merely exists.
 - For local-only or git-only repos, record equivalent closeout context in tracked docs instead of inventing a fake issue queue.
+- In Codex Workspace, a request to update a tracked handover should also trigger the matching `workspace-memory` closeout after the docs update:
+  repo-specific handover updates should run `tools/bin/workspace-memory save-repo <repo-name>`, and workspace-level handover updates should run `tools/bin/workspace-memory save-workspace`.
+- If both repo and workspace handover surfaces changed in one slice, run those MemPalace closeout commands serially so they do not contend on the same local store.
+- Before closing the chat, run a quick `git status` sanity check and confirm any changed public doc surfaces still agree, especially `README.md`, `docs/README.md`, `docs/CHANGELOG.md`, and the relevant repo-local README.
 
 ## What this baseline does not require
 

docs/20-ai-context-side-load.md

@@ -0,0 +1,195 @@
+# 20-ai-context-side-load
+
+## Purpose
+
+This note defines the concrete v1 side-load layer for Codex Workspace.
+
+The goal is to make the existing layered context model operational by generating small, disposable `L0` and `L1` summaries under `cache/context/` without changing the canonical source-of-truth rule.
+
+This note is implementation-specific. It does not replace [07-context-cache-and-retrieval.md](07-context-cache-and-retrieval.md).
+
+## Scope
+
+V1 covers:
+
+- workspace-level summaries
+- one repo-level summary target: `workspace-hub`
+- provenance metadata in `sources.json`
+- a dry-run-first generator script
+- one Workspace Hub read path for repo-detail side-load freshness and file-open actions
+
+V1 does not cover:
+
+- tracked side-load files
+- automatic regeneration during bootstrap or release checks
+- task-bundle generation
+- summary writes from Workspace Hub
+- broad per-repo rollout across every repo in `repos/`
+
+## Canonical versus generated context
+
+The split stays explicit:
+
+- tracked docs, manifests, and repo files remain canonical
+- generated side-load files under `cache/context/` are disposable working summaries
+
+If generated summaries disagree with tracked repo truth, regenerate or ignore the cache.
+
+## Generated layout
+
+V1 generates only these paths:
+
+```text
+cache/context/
+├── workspace/
+│   ├── abstract.md
+│   ├── overview.md
+│   └── sources.json
+└── repos/
+    └── workspace-hub/
+        ├── abstract.md
+        ├── overview.md
+        └── sources.json
+```
+
+Agent-job bundles under `cache/context/agents/jobs/` remain a separate local artifact path created by `tools/scripts/init-agent-job-bundle.sh`.
+
+## Generator
+
+Use:
+
+```bash
+tools/scripts/generate-context-cache.sh --workspace
+tools/scripts/generate-context-cache.sh --workspace --print
+tools/scripts/generate-context-cache.sh --workspace --run
+tools/scripts/generate-context-cache.sh --repo workspace-hub --run
+```
+
+Behavior:
+
+- dry-run by default
+- `--print` shows the generated content on stdout
+- `--run` writes files into `cache/context/`
+- `--repo <name>` resolves a repo name under `repos/` and rejects unsafe path input
+
+## Chat handover protocol
+
+Use this when starting a fresh chat that needs repo-aware handover context.
+
+Recommended sequence:
+
+1. treat tracked docs as canonical and start with the relevant handover or README surface
+2. refresh the side-load cache if the session is broad, new, or likely to re-read workspace context repeatedly
+3. let the chat use generated `abstract.md` and `overview.md` as the fast entry layer
+4. fall back to tracked docs, manifests, and repo files for any real decision or ambiguity
+5. regenerate or ignore the cache if Workspace Hub reports the side-load state as `stale` or `missing`
+
+Practical operator flow:
+
+```bash
+tools/scripts/generate-context-cache.sh --workspace --run
+tools/scripts/generate-context-cache.sh --repo workspace-hub --run
+```
+
+Then start the chat with a handover instruction such as:
+
+> Read `docs/HANDOVER.md` first for the current workspace state. Use generated side-load files under `cache/context/` only as a compact entry layer, and treat tracked docs and repo files as canonical.
+
+For repo-specific work, point the chat at the relevant repo README or handover note as well as the repo side-load cache when it exists.
+
+## Source set
+
+### Workspace
+
+- `README.md`
+- `AGENTS.md`
+- `docs/07-context-cache-and-retrieval.md`
+- `docs/08-first-run-and-updates.md`
+- `docs/09-new-repo-baseline.md`
+- `repos/workspace-hub/README.md`
+
+### Repo: `workspace-hub`
+
+- `repos/workspace-hub/README.md`
+- optional `repos/workspace-hub/AGENTS.md`
+- optional `repos/workspace-hub/.workspace/project.json`
+
+## Summary contracts
+
+### `abstract.md`
+
+Use this as the `L0` entry check.
+
+It should stay small enough for quick relevance decisions and answer:
+
+- what this workspace or repo is
+- what kind of surface it is
+- the main runtime or entrypoint
+- the main constraint or warning
+
+### `overview.md`
+
+Use this as the `L1` planning summary.
+
+It should stay compact enough for planning and answer:
+
+- major directories or surfaces
+- main commands
+- runtime assumptions
+- main rules
+- next canonical docs to open when more detail is needed
+
+## Provenance contract
+
+Each `sources.json` file uses this structure:
+
+```json
+{
+  "version": 1,
+  "scope": "workspace",
+  "target": "workspace",
+  "generatedAt": "2026-04-10T12:00:00Z",
+  "generator": {
+    "path": "tools/scripts/generate-context-cache.sh"
+  },
+  "inputs": [
+    {
+      "path": "README.md",
+      "role": "workspace-readme",
+      "bytes": 14786,
+      "mtimeMs": 1775858522000.0,
+      "sha256": "..."
+    }
+  ],
+  "outputs": [
+    {
+      "path": "cache/context/workspace/abstract.md",
+      "role": "abstract"
+    }
+  ]
+}
+```
+
+Rules:
+
+- `sha256` is stored for provenance and debugging
+- freshness checks compare current file existence and recorded `mtimeMs`
+- output freshness depends on `abstract.md`, `overview.md`, and `sources.json` all existing
+
+## Workspace Hub behavior
+
+Workspace Hub consumes repo side-load data only during repo-detail hydration.
+
+It does not load side-load metadata during the base-summary discovery path.
+
+The details panel should show:
+
+- `missing` when no valid repo side-load cache exists
+- `fresh` when all declared inputs still exist, `mtimeMs` values still match, and required outputs exist
+- `stale` when an input changed or disappeared, or a required output file is missing
+
+The Hub can open the generated `abstract.md`, `overview.md`, and `sources.json` files directly through the existing generic open-path route.
+
+## Practical rule
+
+Use the side-load layer to reduce repeated high-signal doc loading, not to replace tracked workspace guidance.

docs/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 ## 2026-04-10
 
+- Bumped the workspace baseline release to `v1.2.1` and updated `repos/workspace-hub` to `1.2.1` to capture the AI side-load cache flow, handover-closeout automation, and the serialized `workspace-memory` write path.
+- Updated the workspace workflow so an explicit handover-update request now implies the matching `workspace-memory` closeout: repo-scoped handovers should trigger `save-repo`, workspace-scoped handovers should trigger `save-workspace`, and mixed closeout should run serially.
+- Hardened `tools/bin/workspace-memory` write-heavy commands with a re-entrant workspace lock under `cache/mempalace/<user>/locks/`, so overlapping `save-repo`, `save-workspace`, `mine-*`, and `wake-up` runs serialize instead of contending on the same local MemPalace SQLite and Chroma state.
 - Bumped the workspace baseline release to `v1.2.0` and updated `repos/workspace-hub` to `1.2.0` to capture the finished MemPalace search flow, onboarding alignment, Memory Graph Phase 1, and the managed MCP v1 rollout.
+- Added `docs/20-ai-context-side-load.md` plus `tools/scripts/generate-context-cache.sh` so Codex Workspace now has a dry-run-first generator for workspace and `workspace-hub` side-load summaries under ignored `cache/context/` paths.
+- Updated `docs/07-context-cache-and-retrieval.md`, the root README, the docs index, and the Workspace Hub README so the concrete side-load contract, generator entrypoint, and canonical-versus-generated split are discoverable from the public surfaces.
+- Extended `tools/scripts/bootstrap-workspace.sh` to prepare `cache/context/repos/`, and updated Workspace Hub repo details so selected repos can show side-load freshness plus open actions for generated `abstract.md`, `overview.md`, and `sources.json` files without loading side-load metadata on the base-summary path.
 - Hardened the managed Playwright and Chrome DevTools wrappers against bad host environments where `HOME=/`, by falling back to workspace-owned runtime and npm-cache paths under `cache/` and forcing Playwright into isolated mode with a stable output directory.
 - Added the MCP v1 operating-model pack as `docs/15-mcp-profiles-and-trust-levels.md` through `docs/19-mcp-authoring-rules.md`, preserving the existing `10` through `14` docs and turning the older generic MCP note into a concrete support boundary.
 - Added tracked MCP profile and server examples under `tools/templates/mcp/`, plus repo-safe `workspace-hub` examples under `repos/workspace-hub/.workspace/mcp/`.