feat(workspace-hub): add side-load entry packets

Author: RichardGeorgeDavis

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

@@ -220,6 +220,17 @@ Typical contents:
 - its preferred runtime mode
 - its main preview or entry point
 
+### `entry.md`
+
+Repo-scoped routing packet.
+
+Typical contents:
+
+- the default open order for repo work
+- key commands and runtime mode
+- the small set of canonical docs to open next
+- the constraints that should keep the session repo-scoped unless broader context is truly required
+
 ### `overview.md`
 
 `L1` summary.

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

@@ -43,11 +43,13 @@ V1 generates only these paths:
 cache/context/
 ├── workspace/
 │   ├── abstract.md
+│   ├── entry.md
 │   ├── overview.md
 │   └── sources.json
 └── repos/
     └── workspace-hub/
         ├── abstract.md
+        ├── entry.md
         ├── overview.md
         └── sources.json
 ```
@@ -78,9 +80,9 @@ 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
+1. treat tracked docs as canonical and start with the relevant side-load entry packet
 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
+3. let the chat use generated `entry.md`, `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`
 
@@ -95,7 +97,7 @@ 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.
+For repo-specific work, point the chat at the repo `entry.md` first, then the repo README or handover note only when the side-load packet is insufficient.
 
 ## Source set
 
@@ -127,6 +129,18 @@ It should stay small enough for quick relevance decisions and answer:
 - the main runtime or entrypoint
 - the main constraint or warning
 
+### `entry.md`
+
+Use this as the default repo-scoped routing packet.
+
+It should stay compact enough to answer:
+
+- what to open first
+- repo type and runtime mode
+- the main commands
+- the primary canonical docs
+- the main constraints that should prevent broad workspace loading
+
 ### `overview.md`
 
 Use this as the `L1` planning summary.
@@ -188,7 +202,7 @@ The details panel should show:
 - `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.
+The Hub can open the generated `entry.md`, `abstract.md`, `overview.md`, and `sources.json` files directly through the existing generic open-path route.
 
 ## Practical rule
 

docs/CHANGELOG.md

@@ -8,6 +8,8 @@
 - Added a tracked [docs/plans/readme-docs-closeout.md](plans/readme-docs-closeout.md) plan for future reference, and aligned small Workspace Hub/operator copy surfaces with the same mapped-host wording in `repos/workspace-hub`, `tools/scripts/doctor-workspace.sh`, and `tools/scripts/setup-workspace-profile.sh`.
 - Extended `repos/workspace-hub` backlog follow-through with better repo-list prioritization for pinned and recent work, clearer Python-aware dependency readiness, intake-result surfacing in repo details, capability search and inspection, explicit mapped-host routing status, and richer runtime troubleshooting guidance.
 - Advanced Workspace memory graph support from file-open-only toward Phase 2 by surfacing derived-edge counts, node-type breakdown, and an in-app graph report preview for the selected target, while clarifying intentional MCP profile usage in the Workspace Hub settings panel.
+- Added generated `entry.md` side-load packets for workspace and repo context caches, updated manifest support for `entryDocs`, and aligned the side-load docs so Hub operators have one default routing document before they open deeper generated summaries.
+- Split Workspace Hub indexed search into `thin` and `deep` modes so the default path stays fast and side-load-aware while deeper searches can still opt into repo-local docs, logs, and artifact content when that extra cost is justified.
 
 ## 2026-04-10
 

docs/HANDOVER.md

@@ -866,3 +866,33 @@ Verification after this slice:
 Pickup note:
 
 - The managed browser wrappers are now robust even when the host process exposes an unusable home directory; any remaining Playwright-specific failure inside a separate tool host is no longer caused by the workspace wrapper.
+
+### Implementation update (2026-04-11, side-load entry packet and thin/deep search)
+
+Current local workspace changes after `7591ded` focus on the side-load entry path and indexed search behavior.
+
+Completed in the current local slice:
+
+1. Added `entry.md` as the default side-load routing packet.
+   - `tools/scripts/generate-context-cache.sh` now emits `entry.md` for both workspace and repo targets alongside `abstract.md`, `overview.md`, and `sources.json`.
+   - `docs/07-context-cache-and-retrieval.md` and `docs/20-ai-context-side-load.md` now treat `entry.md` as the first compact read for repo-scoped work.
+   - Repo manifests now support optional `entryDocs` so a repo can declare the small set of canonical files operators should open before scanning broadly.
+
+2. Added `thin` versus `deep` indexed search modes in `workspace-hub`.
+   - `thin` is now the default indexed search path and stays focused on repo metadata plus side-load summaries.
+   - `deep` is explicit and expands search into README content, logs, docs, failure reports, and artifacts where those sources exist.
+   - Search document caching is now keyed by mode instead of assuming one global index shape.
+
+3. Updated Hub UI copy and repo details to match the new side-load flow.
+   - Repo Discovery now exposes the indexed-search mode selector.
+   - Repo details can open the generated repo `entry.md` packet directly.
+   - Discovery and manifest docs now explain `entryDocs` plus thin/deep search behavior.
+
+Verification status for this local slice:
+
+- tests were updated for `entry.md` generation, side-load hydration, and thin/deep search behavior
+- final runtime verification for this exact local slice should still be re-run before the next commit or push
+
+Pickup note:
+
+- if this slice lands, update `docs/CHANGELOG.md`, `docs/README.md`, and any relevant `workspace-hub` docs summary so the public side-load contract reflects `entry.md` and the new indexed-search modes

docs/README.md

@@ -49,7 +49,7 @@ Read these in order:
 - `17-mcp-install-and-health-check.md` defines the workspace-owned Codex MCP install, verify, and downgrade path.
 - `18-mcp-server-catalog.md` defines the small approved MCP server catalog for v1.
 - `19-mcp-authoring-rules.md` defines the quality bar for adding future tracked MCP examples.
-- `20-ai-context-side-load.md` defines the concrete v1 side-load generator, provenance contract, and Workspace Hub freshness semantics for generated `cache/context/` summaries.
+- `20-ai-context-side-load.md` defines the concrete v1 side-load generator, `entry.md` routing packet, provenance contract, and Workspace Hub freshness semantics for generated `cache/context/` summaries plus the thin-versus-deep search split.
 - `HANDOVER.md` summarizes the current state of the workspace, current implementation batches, and the latest acceptance evidence.
 - `CHANGELOG.md` records notable workspace-level changes.
 
@@ -79,7 +79,7 @@ Useful maintenance scripts:
 - `tools/scripts/install-mcp-profile.sh` generates and optionally applies the managed Codex Workspace MCP block for a named profile.
 - `tools/scripts/check-mcp-health.sh` verifies the managed MCP block, expected active servers, tracked examples, and wrapper-based browser runtime assumptions.
 - `tools/scripts/init-agent-job-bundle.sh` previews or creates a local cache/context bundle for longer-running agent jobs under `cache/context/agents/jobs/`.
-- `tools/scripts/generate-context-cache.sh` previews or writes workspace and repo side-load summaries under `cache/context/workspace/` and `cache/context/repos/`.
+- `tools/scripts/generate-context-cache.sh` previews or writes workspace and repo side-load summaries under `cache/context/workspace/` and `cache/context/repos/`, including the generated `entry.md` packet that now acts as the default Hub handoff surface.
 - `tools/scripts/release-readiness.sh` runs the stable release gate: workspace doctors, `workspace-hub` test/lint/build, skill-sync dry run, and placeholder-surface checks.
 - `tools/scripts/run-with-workspace-env.sh` runs a command with the shared workspace environment, including the shared Playwright browser cache path.
 - `tools/scripts/setup-workspace-profile.sh` provides a guided, non-destructive profile check for `core`, `hub`, `mixed-stack`, `wordpress`, `agent-enhanced`, `workflow-state`, `spec-driven`, and `ui-previews`.

repos/workspace-hub/README.md

@@ -41,8 +41,8 @@ Workspace Hub is a local control plane for people who manage many standalone rep
 - applies tracked repo-local agent presets for Codex baseline, OMX-ready, OpenCode, or an all-in-one setup directly from the details panel
 - exports the shared workspace Playwright browser cache to repo install and runtime commands by default, so Playwright-based smoke runs can reuse one Chromium download
 - streams live runtime, install, cover, and activity updates from the local API
-- indexes repo metadata, manifests, recent logs, failure reports, and local agent-job artifacts for server-side search
-- reads generated repo side-load summaries on repo-detail hydration so operators can inspect context-cache freshness and open the generated summary files without paying for that metadata on every base summary refresh
+- indexes repo metadata, manifests, side-load summaries, recent logs, failure reports, and local agent-job artifacts for server-side search, with a fast default `thin` mode plus an opt-in `deep` mode for heavier repo content
+- reads generated repo side-load summaries on repo-detail hydration so operators can inspect context-cache freshness and open the generated `entry.md`, `abstract.md`, `overview.md`, and provenance files without paying for that metadata on every base summary refresh
 - exposes a dedicated Workspace memory surface for MemPalace service state, target selection, in-app retrieval search, target-scoped graph builds, and safe wrapper actions
 - builds target-scoped MemPalace graph artifacts from normalized sidecars and nearby markdown instead of introducing a second ingestion engine
 - stores lightweight per-repo metadata and recent activity locally
@@ -201,7 +201,8 @@ pnpm dev:api
 pnpm dev:web --host 127.0.0.1 --port 4174
 curl -s http://127.0.0.1:4101/api/workspace/summary/base | jq '{repoCount: (.repos | length), capabilityCount: (.capabilities | length), firstRepo: (.repos[0] | {relativePath, detailLevel})}'
 curl -s http://127.0.0.1:4101/api/capabilities | jq '{generatedAt, stats}'
-curl -s "http://127.0.0.1:4101/api/search?q=memory" | jq '{total: (.results | length), categories: (.results | map(.category))}'
+curl -s "http://127.0.0.1:4101/api/search?q=memory&mode=thin" | jq '{mode, total: (.results | length), categories: (.results | map(.category))}'
+curl -s "http://127.0.0.1:4101/api/search?q=memory&mode=deep" | jq '{mode, total: (.results | length), categories: (.results | map(.category))}'
 curl -s -X POST http://127.0.0.1:4101/api/services/context -H 'Content-Type: application/json' -d '{"serviceId":"mempalace","targetKind":"workspace-docs"}' | jq '{targetLabel, graph: .graph | {lastBuiltAt, nodeCount, edgeCount}}'
 curl -s -X POST http://127.0.0.1:4101/api/services/command -H 'Content-Type: application/json' -d '{"serviceId":"mempalace","commandId":"search","searchQuery":"workspace memory"}' | jq '{command, ok}'
 curl -s -X POST http://127.0.0.1:4101/api/services/command -H 'Content-Type: application/json' -d '{"serviceId":"mempalace","commandId":"build-graph"}' | jq '{command, ok}'
@@ -238,6 +239,8 @@ Default local endpoints:
 - observability: `http://127.0.0.1:4101/api/workspace/observability`
 - events: `http://127.0.0.1:4101/api/events`
 - search: `http://127.0.0.1:4101/api/search?q=preview`
+- search (thin): `http://127.0.0.1:4101/api/search?q=preview&mode=thin`
+- search (deep): `http://127.0.0.1:4101/api/search?q=preview&mode=deep`
 - capabilities: `http://127.0.0.1:4101/api/capabilities`
 
 Summary endpoints:
@@ -249,6 +252,8 @@ Summary endpoints:
 The UI now prefers base summary for frequent refreshes and hydrates full diagnostics when needed.
 The capability panel now also reads a dedicated read-only capability snapshot so operators can inspect installed, enabled, and reference-only counts without inferring them from the broader workspace summary.
 Repo details now also read optional side-load metadata for the selected repo only, so the `Context cache` block can show `missing`, `fresh`, or `stale` generated summary state without slowing the discovery-first list path.
+The `Context cache` block now treats generated `entry.md` as the default operator handoff packet and can still open the deeper side-load files when needed.
+Indexed search now defaults to `thin` mode so repo discovery, manifest signals, and side-load summaries remain cheap to query, with `deep` mode available when you explicitly want heavier repo-local content included.
 Observability now includes cache hit or miss counters, diagnostics cache behavior, eager repo-details request timing, and summary request reasons to support tuning.
 `/api/workspace/observability` now exposes a versioned schema (`observabilityVersion: 2`) with grouped sections (`discovery`, `diagnostics`, `repoDetails`, `summary`); current top-level counters remain as compatibility aliases for existing consumers.
 
@@ -407,3 +412,5 @@ Current layout note:
   Add deeper per-capability state such as post-install command health or last update output if operators need more than the current read-only snapshot and action feedback.
 - Batch 3: Repo intake polish.
   Tighten intake output so new repos get clearer runtime notes, explicit optional ability dependency guidance when relevant, and better first-run defaults.
+Each generated side-load bundle now includes an `entry.md` routing packet alongside the deeper summaries and provenance files.
+The repo-details panel opens that packet first, and indexed search uses the lighter side-load material by default unless you explicitly switch to `deep` mode.

repos/workspace-hub/docs/discovery.md

@@ -21,7 +21,7 @@ Repo Discovery currently supports:
 - `External repos`
 - repo-type filters such as `vite`, `wordpress`, or `static`
 
-Search matches repo metadata plus archive file names and paths.
+Search defaults to thin indexed metadata plus repo side-load summaries. Deep mode is explicit and expands into debug-only docs, logs, and local artifacts when those sources are available.
 
 ## Dashboard layout
 

repos/workspace-hub/docs/manifest.md

@@ -57,6 +57,7 @@ Workspace Hub currently supports these optional fields:
 - `healthcheckUrl`
 - `servbayPath`
 - `servbaySubdomain`
+- `entryDocs`
 - `tags`
 - `notes`
 
@@ -88,8 +89,9 @@ When Workspace Hub writes a manifest, it uses this order for known fields:
 12. `healthcheckUrl`
 13. `servbayPath`
 14. `servbaySubdomain`
-15. `tags`
-16. `notes`
+15. `entryDocs`
+16. `tags`
+17. `notes`
 
 Unknown preserved keys are appended after the known keys.
 
@@ -108,6 +110,10 @@ Unknown preserved keys are appended after the known keys.
   "previewCommand": "pnpm preview",
   "previewUrl": "http://127.0.0.1:4100",
   "healthcheckUrl": "http://127.0.0.1:4101/api/health",
+  "entryDocs": [
+    "repos/workspace-hub/README.md",
+    "repos/workspace-hub/docs/INSTRUCTIONS.md"
+  ],
   "tags": ["hub", "workspace", "tooling"],
   "notes": "Local-first dashboard for managing mixed-stack repo workspaces."
 }
@@ -127,6 +133,7 @@ Unknown preserved keys are appended after the known keys.
 - Prefer `direct` for Vite, Three.js, and similar frontend repos unless a repo explicitly needs something else.
 - Prefer `external` for WordPress repos already managed by Local or another app.
 - Use `servbayPath` or `servbaySubdomain` only when mapped-host routing is stable and tested (field names are stable JSON keys).
+- Use `entryDocs` for the small set of canonical files the operator should open before scanning the repo broadly.
 - Keep manifests explicit and readable; do not turn them into a dump of every inferred value unless the repo benefits from that clarity.
 - Keep local-only values in `project.local.json` when they should not ship with the repo.
 - If the repo needs a workspace ability for operator workflows, mention the install command in repo docs instead of trying to encode that dependency implicitly in the manifest.

repos/workspace-hub/server/index.ts

@@ -434,6 +434,10 @@ app.get(
     try {
       const query =
         typeof request.query.q === 'string' ? request.query.q.trim() : ''
+      const mode =
+        request.query.mode === 'deep' || request.query.mode === 'thin'
+          ? request.query.mode
+          : 'thin'
 
       if (!query) {
         response.status(400).json({ message: 'A search query is required.' })
@@ -445,6 +449,9 @@ app.get(
         apiPort,
         getInstallSnapshots(),
         getRuntimeSnapshots(),
+        mode === 'deep'
+          ? undefined
+          : { includeDiagnostics: false, repoProjection: 'list' },
       )
 
       response.json(
@@ -453,6 +460,7 @@ app.get(
           summary.repos,
           summary.coreServices,
           summary.capabilities,
+          mode,
         ),
       )
     } catch (error) {

repos/workspace-hub/server/repo-manifest.ts

@@ -10,6 +10,7 @@ import type {
 export type RepoManifestInput = {
   buildCommand?: unknown
   devCommand?: unknown
+  entryDocs?: unknown
   externalUrl?: unknown
   healthcheckUrl?: unknown
   installCommand?: unknown
@@ -51,6 +52,7 @@ const orderedManifestKeys = [
   'healthcheckUrl',
   'servbayPath',
   'servbaySubdomain',
+  'entryDocs',
   'tags',
   'notes',
 ] as const
@@ -78,6 +80,17 @@ function normalizeTags(value: unknown) {
     .filter(Boolean)
 }
 
+function normalizeEntryDocs(value: unknown) {
+  if (!Array.isArray(value)) {
+    return []
+  }
+
+  return value
+    .filter((entry): entry is string => typeof entry === 'string')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+}
+
 async function readExistingManifest(manifestPath: string) {
   try {
     return JSON.parse(await readFile(manifestPath, 'utf8')) as Record<string, unknown>
@@ -129,11 +142,13 @@ export function normalizeManifestInput(input: RepoManifestInput) {
   }
 
   const normalizedTags = normalizeTags(input.tags)
+  const normalizedEntryDocs = normalizeEntryDocs(input.entryDocs)
   const notes = normalizeOptionalString(input.notes)
 
   return {
     buildCommand: normalizeOptionalString(input.buildCommand),
     devCommand: normalizeOptionalString(input.devCommand),
+    entryDocs: normalizedEntryDocs.length ? normalizedEntryDocs : undefined,
     externalUrl: normalizeOptionalString(input.externalUrl),
     healthcheckUrl: normalizeOptionalString(input.healthcheckUrl),
     installCommand: normalizeOptionalString(input.installCommand),