Harden workspace manifest validation and search caching

Author: RichardGeorgeDavis

README.md

@@ -281,15 +281,17 @@ Current workspace source taxonomy:
 - `repo-level adoption` lives under normal `repos/...`
 - `core service` lives under `tools/<name>/` with durable state in `shared/<name>/<user>/` and disposable state in `cache/<name>/<user>/`
 
-External skill catalogs such as [`openai/skills`](https://github.com/openai/skills) and upstream design catalogs such as [`VoltAgent/awesome-design-md`](https://github.com/VoltAgent/awesome-design-md) should be treated as optional reviewed sources, not vendored workspace dependencies.
+External skill catalogs such as [`openai/skills`](https://github.com/openai/skills), the canonical [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md) spec/tooling, and example catalogs such as [`VoltAgent/awesome-design-md`](https://github.com/VoltAgent/awesome-design-md) should be treated as optional reviewed sources, not vendored workspace dependencies.
 
 - install only the specific skills that solve a real workflow need
 - prefer local skill installation via Codex tooling such as `$skill-installer`
 - for repo-level Codex discoverability, prefer tracked `.codex/skills/` and keep `.agents/skills/` only when repo-local compatibility mirroring helps
 - keep workspace-wide reusable skill sources in `shared/skills/` and starter templates in `tools/templates/skills/`
-- keep the managed VoltAgent `DESIGN.md` catalog as an optional ability under `repos/abilities/voltagent-awesome-design-md` and copy only the specific `DESIGN.md` files a repo actually needs
+- treat `google-labs-code/design.md` as the canonical repo-level `DESIGN.md` standard and use `tools/scripts/design-md.sh` to initialize, lint, and diff repo-owned `DESIGN.md` files
+- keep repo-root `DESIGN.md` optional and per-repo, recommended mainly for UI-heavy repos rather than the whole workspace
+- keep the managed VoltAgent `DESIGN.md` catalog as an optional example ability under `repos/abilities/voltagent-awesome-design-md` and copy only the specific example files a repo actually needs
 - use `tools/scripts/capture-site-reference.sh` when a repo needs a conservative `httrack`-based public-site reference capture plus a repo-local acquisition note under `ref/httrack/`
-- use `tools/scripts/use-design-md.sh` when you want a stable local mirror under `cache/design-md/catalog/` or need to copy one `DESIGN.md` into a repo root quickly
+- use `tools/scripts/use-design-md.sh` only for the VoltAgent example catalog mirror under `cache/design-md/catalog/`
 - keep third-party orchestration layers and generated agent setup local-only unless there is a strong reason to publish them
 - do not add the whole upstream skill catalog to `repos/`, `tools/`, or as a submodule unless there is a very specific maintenance reason
 

docs/06-cross-agent-skills-and-mcp.md

@@ -52,14 +52,21 @@ Treat upstream skill catalogs such as [`openai/skills`](https://github.com/opena
 - keep `.agents/skills/` only as an optional compatibility mirror when needed
 - keep shared reusable source material in `shared/skills/` and `tools/templates/skills/`
 
-Treat upstream design catalogs such as [`VoltAgent/awesome-design-md`](https://github.com/VoltAgent/awesome-design-md) similarly:
+Treat repo-level `DESIGN.md` in two layers:
 
-- classify it as an optional workspace `ability`
+- use [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md) as the canonical workspace standard for repo-owned `DESIGN.md` files
+- keep repo-root `DESIGN.md` optional and per-repo, recommended mainly for UI-heavy repos
+- initialize, lint, and diff those files through `tools/scripts/design-md.sh`
+- keep one repo's `DESIGN.md` local to that repo instead of inventing a shared cross-repo design file
+
+Treat upstream example catalogs such as [`VoltAgent/awesome-design-md`](https://github.com/VoltAgent/awesome-design-md) similarly:
+
+- classify the catalog as an optional workspace `ability`
 - keep the managed catalog as a standalone repo under `repos/abilities/voltagent-awesome-design-md`
 - refresh it with `tools/scripts/manage-workspace-capabilities.sh update --run voltagent-awesome-design-md` when you want newer `DESIGN.md` files
-- copy only the specific `DESIGN.md` files a repo needs into that repo instead of making the catalog a shared runtime dependency
+- use it as example source material only, and copy only the specific `DESIGN.md` files a repo needs into that repo instead of making the catalog a shared runtime dependency
 
-The reviewed update flow now uses one classification-aware lifecycle: snapshot sources such as `openai/skills` and `openai/codex` stay under `tools/ref/`, optional abilities such as `VoltAgent/awesome-design-md` live under `repos/abilities/`, and core workspace services live under `tools/`.
+The reviewed update flow now uses one classification-aware lifecycle: snapshot sources such as `openai/skills` and `openai/codex` stay under `tools/ref/`, optional abilities such as `google-labs-code/design.md` and `VoltAgent/awesome-design-md` live under `repos/abilities/`, and core workspace services live under `tools/`.
 
 Third-party orchestration layers that generate `AGENTS.md`, skills folders, or MCP config should remain optional local tooling by default rather than becoming the canonical workspace layout.
 

docs/09-new-repo-baseline.md

@@ -37,6 +37,7 @@ This is not meant to force every repo into one shape. The goal is to keep each r
 When useful, add small explicit metadata instead of hidden assumptions:
 
 - `.workspace/project.json` for runtime mode, launch command, preview URL, or notes
+- `DESIGN.md` at the repo root when the repo has meaningful UI or design-system work and needs a tracked visual language reference
 - `.workspace/agent-stack.json` when the repo intentionally supports tracked multi-tool agent hints such as OMX-ready or OpenCode-ready setup
 - `README.md` for repo purpose, setup, run instructions, preview notes, and cover block
 - `docs/cover.png` as the default repo-local cover path, even if it starts as a placeholder
@@ -76,9 +77,10 @@ Recommended intake order:
 4. Create `README.md` if it is missing, or tighten the current one if it exists but does not explain setup and preview.
 5. Add a runnable launcher command file so the repo can be started without remembering the shell incantation.
 6. Add a repo-local cover image reference in the README, even if the image is a placeholder at first.
-7. Add `.workspace/project.json` only when runtime behavior is not obvious from the repo files.
-8. Add repo-level `AGENTS.md`, `HANDOVER.md`, or repo-local skills only when they solve a real repo-specific need.
-9. If README, HANDOVER, or durable setup docs were created or materially updated, run `tools/bin/workspace-memory save-repo <repo-path-or-name>` so the shared memory layer captures the repo state, related workspace docs, and the current Codex thread in one closeout step.
+7. Add repo-root `DESIGN.md` only when the repo would benefit from tracked UI or design-system guidance; do not add it mechanically to every repo.
+8. Add `.workspace/project.json` only when runtime behavior is not obvious from the repo files.
+9. Add repo-level `AGENTS.md`, `HANDOVER.md`, or repo-local skills only when they solve a real repo-specific need.
+10. If README, HANDOVER, `DESIGN.md`, or other durable setup docs were created or materially updated, run `tools/bin/workspace-memory save-repo <repo-path-or-name>` so the shared memory layer captures the repo state, related workspace docs, and the current Codex thread in one closeout step.
 
 For MemPalace target metadata, prefer `.workspace/mempalace/` inside the repo rather than dropping `mempalace.yaml` or `entities.json` at the repo root.
 
@@ -94,6 +96,8 @@ Use a placeholder image first if a real preview capture is not ready yet. Keepin
 
 The starter files in `tools/templates/repo-docs/` are the default template source for this intake step.
 
+For UI-heavy repos that need tracked design-system context, the starter source for a repo-local `DESIGN.md` now lives in `tools/templates/design-md/`, and the canonical wrapper is `tools/scripts/design-md.sh`.
+
 ## Implementation batches
 
 Use batches when a repo has enough pending work that a future chat should be able to pick up one complete slice at a time.

docs/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2026-04-22
+
+- Added `tools/scripts/design-md.sh` as the canonical repo-level `DESIGN.md` wrapper for starter-template init, `@google/design.md` lint/diff, and optional delegation to the VoltAgent example catalog.
+- Added `tools/templates/design-md/` with a Google-spec-aligned starter `DESIGN.md` template so UI-heavy repos can adopt repo-root design context without inventing a shared workspace-wide design file.
+- Registered `google-labs-code/design.md` as the canonical optional workspace ability, while explicitly retaining `VoltAgent/awesome-design-md` as the optional example catalog path.
+- Updated [README](../README.md), [docs/README](README.md), [06-cross-agent-skills-and-mcp](06-cross-agent-skills-and-mcp.md), and [09-new-repo-baseline](09-new-repo-baseline.md) so `DESIGN.md` is documented as an opt-in per-repo surface, recommended for UI-heavy repos only.
+- Added lightweight Workspace Hub detection for repo-root `DESIGN.md` presence so repo details can surface it without introducing a new manifest layer.
+
 ## 2026-04-17
 
 - Added `tools/scripts/workspace-port-allocator.sh` and rewired the workspace-level launchers under `tools/local/commands/` to reserve ports through `cache/runtime/ports/`, reducing same-time launcher collisions while keeping hosts fixed on `127.0.0.1` and falling forward to the next open port in each repo's range.

docs/HANDOVER.md

@@ -159,6 +159,50 @@ The workspace launcher baseline is now:
 
 This is intended to reduce same-time launcher collisions without making local URLs unpredictable.
 
+## `DESIGN.md` capability note (2026-04-22)
+
+The workspace now has a canonical per-repo `DESIGN.md` path.
+
+Current stance:
+
+- treat [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md) as the canonical `DESIGN.md` standard for this workspace
+- keep repo-root `DESIGN.md` optional and per-repo, recommended mainly for UI-heavy repos
+- use `tools/scripts/design-md.sh` for the repo-owned workflow:
+  - `init` copies the tracked starter template into repo-root `DESIGN.md`
+  - `lint` runs `npx -y @google/design.md lint`
+  - `diff` runs `npx -y @google/design.md diff`
+  - `examples ...` delegates to the existing VoltAgent-backed example catalog flow
+- keep `tools/scripts/use-design-md.sh` as the optional VoltAgent example-catalog wrapper, not as the canonical authoring workflow
+- keep copied or authored `DESIGN.md` files inside the individual repo that owns them rather than inventing one shared workspace-wide design file
+
+Tracked surfaces added in this slice:
+
+- `tools/scripts/design-md.sh`
+- `tools/templates/design-md/`
+- `tools/manifests/workspace-capabilities.json` entry for `google-labs-code/design.md`
+- Workspace Hub repo-details detection for repo-root `DESIGN.md`
+
+Verification completed in this slice:
+
+- `sh -n tools/scripts/design-md.sh tools/scripts/use-design-md.sh`
+- `pnpm --dir "repos/workspace-hub" typecheck`
+- targeted `workspace-hub` tests covering the new wrapper, template flow, and repo detection
+- live smoke of the real CLI:
+  - `tools/scripts/design-md.sh init <tmpdir>`
+  - `tools/scripts/design-md.sh lint <tmpdir>` returned `0` errors and `0` warnings on the starter template
+  - `tools/scripts/design-md.sh diff <tmpdir> <tmpdir>/DESIGN-v2.md` reported the expected token change
+  - a deliberately invalid color fixture produced a structured lint error
+
+Public docs now aligned for this feature:
+
+- `README.md`
+- `docs/README.md`
+- `docs/CHANGELOG.md`
+- `docs/06-cross-agent-skills-and-mcp.md`
+- `docs/09-new-repo-baseline.md`
+
+Repo-local `repos/workspace-hub/README.md` did not need a matching public-doc update for this slice because the change there is limited to lightweight repo-details detection rather than a new end-user Hub workflow surface.
+
 ## Release verification status
 
 The stable release gate has already been exercised successfully:

docs/README.md

@@ -85,10 +85,11 @@ Useful maintenance scripts:
 - `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`.
 - `tools/scripts/manage-workspace-capabilities.sh` lists, installs, updates, enables, disables, or uninstalls tracked workspace abilities and core services, with dry-run mode by default.
+- `tools/scripts/design-md.sh` is the canonical repo-level `DESIGN.md` wrapper for starter-template init, `@google/design.md` lint/diff, and example-catalog delegation.
 - `tools/scripts/update-github-refs.sh` remains the compatibility wrapper for update-only reviewed GitHub-ref flows and delegates to the capability lifecycle command.
 - `tools/scripts/capture-site-reference.sh` previews or runs an `httrack` capture for a public-site reference repo, using conservative same-domain defaults and writing capture notes under repo-local `ref/httrack/`.
 - `tools/scripts/workspace-port-allocator.sh` centralizes workspace launcher port reservations under `cache/runtime/ports/`, so concurrent launchers can keep `127.0.0.1` stable and step to the next open port without colliding.
-- `tools/scripts/use-design-md.sh` mirrors the managed VoltAgent `DESIGN.md` catalog ability into `cache/design-md/catalog/`, lists available site ids, and can copy a selected `DESIGN.md` into a repo root.
+- `tools/scripts/use-design-md.sh` mirrors the managed VoltAgent example `DESIGN.md` catalog ability into `cache/design-md/catalog/`, lists available site ids, and can copy a selected example `DESIGN.md` into a repo root.
 - `tools/scripts/sync-reference-snapshots.sh` previews or refreshes ignored upstream reference snapshots under `tools/ref/`, with dry-run mode by default.
 - `tools/scripts/sync-codex-skills.sh` previews or syncs tracked workspace skill sources into repo `.codex/skills/` folders plus optional `.agents/skills/` compatibility mirrors, with dry-run mode by default.
 - `tools/scripts/trim-git-repos.sh` performs safe Git maintenance across `repos/` by cleaning `.git` sync noise, expiring older reflog entries, and running `git gc` with a conservative prune window.
@@ -103,6 +104,7 @@ Useful template locations:
 
 - `tools/templates/skills/` holds starter skill packs, execution-mode conventions, and a selective install-profile example.
 - `tools/templates/repo-docs/` holds a starter repo `README.md` template plus a placeholder cover image for new repo intake.
+- `tools/templates/design-md/` holds the canonical repo-level `DESIGN.md` starter template and notes for UI-heavy repos that want tracked design-system context.
 - `tools/templates/codex/` holds starter material for official repo-local `.codex/` setup.
 - `tools/templates/opencode/` holds starter material for optional `.opencode/` setup plus mixed-tool agent presets.
 - `tools/templates/mcp/` holds the official MCP v1 profile and server examples, env templates, generic `read-only` versus `mutating` starter examples, and stdio/logging hygiene notes.

repos/workspace-hub/server/core-service-runtime.ts

@@ -11,6 +11,7 @@ import type {
   WorkspaceCoreServiceCommandId,
 } from '../src/types/workspace.ts'
 import { publishWorkspaceEvent } from './live-events.ts'
+import { invalidateWorkspaceSearchIndex } from './workspace-search.ts'
 
 type ManagedServiceRuntime = {
   child: ChildProcess
@@ -139,7 +140,7 @@ export async function startCoreService(service: WorkspaceCoreService) {
     throw new Error(`${service.name} is already running.`)
   }
 
-  const child = spawn(service.runtimeCommand, [], {
+  const child = spawn(service.runtimeCommandArgs[0], service.runtimeCommandArgs.slice(1), {
     cwd: service.repoPresent ? service.repoPath : undefined,
     env: process.env,
     stdio: ['ignore', 'pipe', 'pipe'],
@@ -236,7 +237,7 @@ export async function runCoreServiceInstall(service: WorkspaceCoreService) {
     throw new Error(`${service.name} install is already running.`)
   }
 
-  const child = spawn(service.installCommand, [], {
+  const child = spawn(service.installCommandArgs[0], service.installCommandArgs.slice(1), {
     cwd: service.repoPresent ? service.repoPath : undefined,
     env: process.env,
     stdio: ['ignore', 'pipe', 'pipe'],
@@ -284,6 +285,7 @@ export async function runCoreServiceInstall(service: WorkspaceCoreService) {
       status: record.snapshot.status,
       type: 'service',
     })
+    invalidateWorkspaceSearchIndex('core-service-install')
   })
 
   publishWorkspaceEvent({
@@ -295,7 +297,7 @@ export async function runCoreServiceInstall(service: WorkspaceCoreService) {
 }
 
 export async function runCoreServiceSync(service: WorkspaceCoreService) {
-  await execFileAsync(service.syncCommand, [], {
+  await execFileAsync(service.syncCommandArgs[0], service.syncCommandArgs.slice(1), {
     cwd: service.repoPresent ? service.repoPath : undefined,
     env: process.env,
     maxBuffer: 1024 * 512,
@@ -308,6 +310,7 @@ export async function runCoreServiceSync(service: WorkspaceCoreService) {
     status: 'ready',
     type: 'service',
   })
+  invalidateWorkspaceSearchIndex('core-service-sync')
 }
 
 type CoreServiceCommandOptions = {