coding-os 0.3.2__py3-none-any.whl

templates/meta/skills/meta-engineering/assets/meta-edit-checklist.md

@@ -0,0 +1,28 @@
+<!-- domain:META | layer:asset | ssot:false | updated:2026-06-04 -->
+# Meta-Repo Edit Checklist
+
+Run before editing anything under core/ · cli/ · adapters/ · templates/ · hooks/.
+
+## Before the edit
+- [ ] Know the layer + blast radius — `python3 scripts/which_layer.py <path>`.
+- [ ] Editing the LOWEST correct layer (more reuse) — not duplicating into a higher one.
+- [ ] Graph context loaded (`cos_graph_context`) for `src/core/**`, `src/cli/**`, `src/adapters/**` `.py`.
+- [ ] `Skill graph-explorer` + `Skill clean-code` loaded; COMPLICATED+ adds `Skill thinking_os`.
+- [ ] Doc anchor recorded (every code edit traces to a spec).
+- [ ] Task marker names a governance/docs-update/template-update task for governance/registry/rule-SSOT edits.
+
+## Layer-specific (after the edit)
+- [ ] `src/core/hooks/**` → registered in registry.yaml → `make regen-adapter-templates` → `make verify-hooks`.
+- [ ] `src/core/thinking_os/**` → `uv run --extra rag pytest src/core/thinking_os/tests/ -q` + server `--test`.
+- [ ] `src/templates/**` (dimensions/skill_enforcement) → `make regen-rules`.
+- [ ] `src/adapters/<id>/**` → `bash src/adapters/<id>/install.sh`.
+- [ ] `src/cli/**` → `uv run pytest tests/test_cli.py tests/test_no_hardcoded_*.py -q`.
+
+## Never
+- [ ] Hand-edit a regen target (dimension-registry.md, skill-enforcement.md, golden/, adapter templates).
+- [ ] Hardcode `.claude/` in src/core/ — use `$COS_AGENT_DIR`/`$COS_STATE_DIR`.
+- [ ] Run `cos init` inside the meta-repo.
+- [ ] Full `pytest tests/ -q` mid-task — matrix-targeted only.
+
+## Propagation confirmed
+- [ ] Dogfood: `make dogfood` (or `make dogfood-full`) re-rendered + still green.

templates/meta/skills/meta-engineering/scripts/which_layer.py

@@ -0,0 +1,61 @@
+"""Classify a meta-repo path into its DNA→mRNA→phenotype layer + propagation.
+
+PURPOSE:      Answer "which layer does this file belong to, and how does an edit
+              reach consumers?" before editing — the most common meta-repo
+              mis-step is editing the wrong layer.
+INPUT:        one or more repo-relative paths. [--json]
+OUTPUT:       layer + propagation per path on stdout. Exit 0; 2 usage.
+DEPENDENCIES: stdlib only.
+NOTES:        Pure classify() is unit-testable. Mirrors AGENTS.md Modularity Map.
+              Spec: docs/architecture/meta-project.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+# (path-prefix, layer, propagation) — first match wins; order most-specific first.
+RULES: list[tuple[str, str, str]] = [
+    ("src/core/hooks/", "DNA (core)", "live symlink — reaches every consumer immediately"),
+    ("src/core/thinking_os/", "DNA (core)", "MCP server restart picks it up"),
+    ("src/core/graph_os/", "DNA (core)", "MCP server restart"),
+    ("src/core/board_os/", "DNA (core)", "MCP server restart"),
+    ("src/core/rules/", "DNA (core)", "live symlink + `cos update` in consumer"),
+    ("src/core/skills/", "DNA (core)", "live symlink + `cos update` in consumer"),
+    ("src/core/web/", "DNA (core)", "hub restart / `cos hub restart`"),
+    ("src/core/", "DNA (core)", "varies — see Modularity Map"),
+    ("src/adapters/", "mRNA (adapter)", "`bash src/adapters/<id>/install.sh` (manual)"),
+    ("src/templates/", "phenotype (stack)", "`cos update` + `make manifest-regen` (manual)"),
+    ("src/cli/", "factory (CLI)", "new `cos` invocations after `uv tool install --editable .`"),
+    ("docs/", "docs", "meta-repo only unless in the base/stack scaffold"),
+    ("tests/", "tests", "meta-repo only — never ships"),
+]
+
+
+def classify(path: str) -> tuple[str, str]:
+    p = path.lstrip("./")
+    for prefix, layer, propagation in RULES:
+        if p.startswith(prefix):
+            return layer, propagation
+    return "unknown", "not a recognized meta-repo layer path"
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("paths", nargs="+")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    rows = [{"path": p, "layer": (c := classify(p))[0], "propagation": c[1]} for p in args.paths]
+    if args.as_json:
+        print(json.dumps(rows, indent=2))
+    else:
+        for r in rows:
+            print(f"{r['path']}\n  layer: {r['layer']}\n  reaches consumer: {r['propagation']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

templates/meta/skills/python-meta-server/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: python-meta-server
+tier: stack
+domain: [architecture]
+description: Use when authoring or modifying Python code in the meta-repo's server / kernel — MCP tools (src/core/thinking_os/), graph extractors (src/core/graph_os/), board engine (src/core/board_os/), hooks helpers (src/core/hooks/_helpers/), and CLI (cli/). Codifies the FastMCP envelope contract, type-hint discipline, async patterns, exception hierarchy, and the regen pipelines specific to this codebase. Pairs with graph-explorer (always primary), meta-engineering, and clean-code.
+last_reviewed: "2026-05-11"
+
+---
+
+# python-meta-server
+
+Purpose: Internalise the Python authoring conventions that make this
+meta-repo work — MCP envelope, FastMCP registration, schema migrations,
+extractor idempotency, hook helper structure. Without this skill,
+agents write Python that LOOKS correct but breaks the contracts that
+every consumer project depends on.
+
+Read when: editing any of:
+- `src/core/thinking_os/**/*.py` — MCP server, tools, dispatcher, cognition.
+- `src/core/graph_os/**/*.py` — backends, extractors, ingestion.
+- `src/core/board_os/**/*.py` — Scrumban engine.
+- `src/core/hooks/_helpers/**/*.py` — hook helpers.
+- `src/cli/**/*.py` — factory CLI.
+- `src/core/web/server.py`, `src/core/web/routes/**/*.py` — FastAPI routes.
+
+Skip when: editing tests (`*test*.py`), scripts (`scripts/`), or one-off helpers.
+
+## Hard contracts
+
+### 1. MCP envelope — Rule 13 (NON-NEGOTIABLE)
+
+Every `cos_*` MCP tool returns either:
+
+```python
+{"ok": True,  "data": <payload>, "meta": {"layer": "<layer>", ...}}
+{"ok": False, "error": {"category": "<cat>", "message": "<human>", "retryable": <bool>}}
+```
+
+Use `@safe_tool` from `src/core/thinking_os/tools/_shared.py`:
+
+```python
+from thinking_os.tools._shared import safe_tool, ok, fail
+
+@safe_tool
+@mcp.tool()
+def cos_my_tool(arg: str) -> dict:
+    """One-line description for FastMCP."""  # ← Rule 12
+    if not arg:
+        return fail("validation", "arg must be non-empty")
+    return ok({"result": ...}, meta={"layer": "thinking_os"})
+```
+
+Categories: `validation` · `not_found` · `unavailable` (retryable) · `conflict` (retryable) · `internal`.
+
+### 2. Docstrings — Rule 12
+
+ONE-line docstring on `@mcp.tool` functions only — FastMCP exposes
+that line as the agent-facing description. NO multi-line docstrings on
+internal helpers. Comments by exception, not by default.
+
+### 3. Schema migrations — Rule 9
+
+Adding a persistent table: write `src/core/thinking_os/migrations/vN+1_<name>.sql`.
+NEVER edit a previous migration. `tests/test_db.py` guards the invariant.
+
+### 4. Extractor idempotency
+
+Every graph extractor:
+- Keys nodes by stable `uid` (e.g. `code:function:<path>::<name>`).
+- Short-circuits via `file_index_state` content_hash when the file's
+  hash matches the last extraction.
+- Never returns duplicate uids in one batch.
+
+### 5. Async + FastMCP
+
+MCP tool functions can be sync OR async. If async, do NOT block the
+event loop with sync I/O — wrap in `asyncio.to_thread` or use
+`anyio.to_thread.run_sync`.
+
+### 6. CLI no-hardcode (Rule 11)
+
+`src/cli/**/*.py` MUST NOT hardcode stack/adapter literals. Discover via:
+- `cli.adapter_registry.load_adapter_registry()`
+- `cli.stack_registry.load_stack_registry()`
+
+Tests `tests/test_no_hardcoded_anthropic.py` + `tests/test_no_hardcoded_stacks.py` enforce.
+
+## Pre-edit moves
+
+1. `cos_graph_resolve("the function I want to edit")` → canonical uid.
+2. `cos_graph_context(uid, depth=1)` → neighbours + types + decorators.
+3. `cos_graph_references(uid)` → who calls / depends on it.
+4. For signature change: `cos_graph_impact(uid, direction="downstream", depth=3)`.
+5. For rename: `cos_graph_rename_plan(uid, new_name)`.
+6. THEN Read the file (max 1).
+
+## Common patterns
+
+### Defensive imports for optional deps
+
+```python
+try:
+    import sentence_transformers
+    _HAS_EMBEDDINGS = True
+except ImportError:
+    _HAS_EMBEDDINGS = False
+```
+
+### Telemetry without blocking
+
+```python
+def _emit(meta: dict) -> None:
+    try:
+        with open(path, "a") as f:
+            f.write(json.dumps(...) + "\n")
+    except OSError as exc:
+        logger.debug("telemetry skipped: %s", exc)  # fail-open
+```
+
+### Path resolution (Rule 5 — macOS quirk)
+
+```python
+# /tmp ↔ /private/tmp on macOS — always resolve before relative_to
+real = Path(p).resolve()
+rel = real.relative_to(REPO_ROOT.resolve())
+```
+
+## Anti-patterns
+
+- **Multi-paragraph docstrings on internal helpers** — Rule 12 violation.
+- **Direct sqlite3 in tool layer** — must go through `GraphBackend` interface.
+- **Editing previous migration** — Rule 9 violation; new tables → vN+1.
+- **Bare `except Exception` without logging** — fail-open helpers must log at debug.
+- **Importing from `adapters/` inside `core/`** — P8 violation (Adapter-SDK autonomy).
+- **Hardcoding `.claude/` literal** — P2 violation; use `$COS_AGENT_DIR` env var.
+
+## Verification matrix
+
+| Changed | Command |
+|---|---|
+| `src/core/thinking_os/**` | `uv run --extra rag pytest src/core/thinking_os/tests/ -q` + `python src/core/thinking_os/server.py --test` |
+| `src/core/graph_os/**` | `uv run --extra graph_os pytest src/core/graph_os/tests/ -q` |
+| `src/core/board_os/**` | `uv run --extra rag --with aiohttp --with pytest-asyncio pytest src/core/board_os/tests/ -q` |
+| `src/cli/**` | `uv run pytest tests/test_cli.py -q` |
+| `src/core/web/**` | hub smoke + the relevant test_* in tests/ |
+| Schema migration | `uv run --extra rag pytest src/core/thinking_os/tests/test_db.py -q` |
+
+NEVER run `pytest tests/ -q` mid-task — that's the 6-minute full-sweep gate, pre-merge only.
+
+## Tooling
+
+Lint MCP tools for the envelope contract (Rule 13/2 — @safe_tool, cos_ prefix, ok/fail):
+`python3 scripts/check_envelope.py src/core/thinking_os/tools/*.py`
+
+## See also
+
+- [assets/meta-server-checklist.md](assets/meta-server-checklist.md) — the kernel-Python gate.
+- [docs/engineering/mcp-error-envelope.md](../../../../docs/engineering/mcp-error-envelope.md)
+- [docs/engineering/graph_os-queries.md](../../../../docs/engineering/graph_os-queries.md)
+- [docs/governance/critical-rules.md](../../../../docs/governance/critical-rules.md)
+- [src/templates/meta/rules/mcp-tool-author.md](../../rules/mcp-tool-author.md)
+- [src/templates/meta/rules/hook-author.md](../../rules/hook-author.md)

templates/meta/skills/python-meta-server/assets/meta-server-checklist.md

@@ -0,0 +1,28 @@
+<!-- domain:META | layer:asset | ssot:false | updated:2026-06-04 -->
+# Meta-Server Python Checklist
+
+Run when editing Python in the kernel (thinking_os / graph_os / board_os / hooks helpers / cli).
+
+## Envelope + tools (Rule 13/2/12)
+- [ ] Every `@mcp.tool()` also `@safe_tool`; returns `ok()`/`fail()`.
+- [ ] Tool name `cos_`-prefixed; one-line docstring only (it's the agent description).
+- [ ] `python3 scripts/check_envelope.py <tools file>` → `clean`.
+
+## Types + style
+- [ ] Type hints on every function signature (params + return).
+- [ ] `from __future__ import annotations` at the top of new modules.
+- [ ] Internal helpers have NO docstrings (Rule 12); comments by exception.
+- [ ] Fire-and-forget wrapped in `_*_safe()` with `except Exception as exc: logger.debug(...)` (Rule 6).
+- [ ] `Path(...).resolve()` before `.relative_to()` (Rule 5).
+
+## Schema (Rule 9)
+- [ ] New persistent table → `migrations/vN+1_<name>.sql` (append-only); no past migration edited.
+
+## Multi-step verification (Rule 8)
+- [ ] No bash heredoc inside `uv run` — extract to a Python helper.
+
+## Verify (matrix-targeted)
+- [ ] thinking_os → `uv run --extra rag pytest src/core/thinking_os/tests/ -q` + server `--test`.
+- [ ] graph_os → `uv run --extra graph_os pytest src/core/graph_os/tests/ -q`.
+- [ ] board_os → `uv run --extra rag --with aiohttp --with pytest-asyncio pytest src/core/board_os/tests/ -q`.
+- [ ] cli → `uv run pytest tests/test_cli.py -q`.

templates/meta/skills/python-meta-server/scripts/check_envelope.py

@@ -0,0 +1,91 @@
+"""Flag cos_* MCP tools that violate the envelope contract (Rule 13).
+
+PURPOSE:      Catch a @mcp.tool that lacks @safe_tool or doesn't return ok/fail
+              before it ships — the envelope is what every caller + test relies on.
+INPUT:        one or more tools/*.py paths. [--json]
+OUTPUT:       Findings (file:line) on stderr; "clean"/"N finding(s)" on stdout.
+              Exit 0 clean, 1 if findings, 2 usage.
+DEPENDENCIES: stdlib only (ast — accurate, not regex).
+NOTES:        Pure scan_source() is unit-testable. Spec:
+              docs/engineering/mcp-error-envelope.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import sys
+from pathlib import Path
+
+
+def _decorator_names(node: ast.FunctionDef) -> set[str]:
+    names: set[str] = set()
+    for dec in node.decorator_list:
+        target = dec.func if isinstance(dec, ast.Call) else dec
+        if isinstance(target, ast.Name):
+            names.add(target.id)
+        elif isinstance(target, ast.Attribute):
+            names.add(target.attr)
+    return names
+
+
+def _returns_envelope(node: ast.FunctionDef) -> bool:
+    for sub in ast.walk(node):
+        if isinstance(sub, ast.Return) and isinstance(sub.value, ast.Call):
+            fn = sub.value.func
+            if isinstance(fn, ast.Name) and fn.id in {"ok", "fail"}:
+                return True
+    return False
+
+
+def scan_source(text: str, *, filename: str = "?") -> list[str]:
+    findings: list[str] = []
+    tree = ast.parse(text)
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.FunctionDef):
+            continue
+        decs = _decorator_names(node)
+        if "tool" not in decs:  # only @mcp.tool() functions
+            continue
+        if "safe_tool" not in decs:
+            findings.append(
+                f"{filename}:{node.lineno}: {node.name} is @mcp.tool but not @safe_tool (Rule 13)"
+            )
+        if not node.name.startswith("cos_"):
+            findings.append(f"{filename}:{node.lineno}: {node.name} missing cos_ prefix (Rule 2)")
+        if not _returns_envelope(node):
+            findings.append(
+                f"{filename}:{node.lineno}: {node.name} never returns ok()/fail() (Rule 13)"
+            )
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("files", nargs="+")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    all_findings: list[str] = []
+    for path in args.files:
+        try:
+            all_findings.extend(scan_source(Path(path).read_text(encoding="utf-8"), filename=path))
+        except FileNotFoundError:
+            print(f"error: {path} not found", file=sys.stderr)
+            return 2
+        except SyntaxError as exc:
+            print(f"error: {path}: {exc}", file=sys.stderr)
+            return 2
+
+    for f in all_findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"findings": all_findings, "count": len(all_findings)}))
+    else:
+        print("clean" if not all_findings else f"{len(all_findings)} finding(s)")
+    return 1 if all_findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

templates/meta/skills/react-vite-hub/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: react-vite-hub
+tier: stack
+domain: [frontend]
+description: Use when authoring or modifying the meta-repo's Hub UI in src/core/web/ui/ — React 18 + Vite + TypeScript + Sigma.js graph canvas + zustand state. Covers the contract between FastAPI routes (src/core/web/routes/) and the SPA, env vars (VITE_*), build pipeline, hot-reload dev mode, and how the Hub UI proxies into per-project /api/p/<slug>/* endpoints. Pairs with frontend-fundamentals, a11y, and graph-explorer (when touching graph visualization).
+last_reviewed: "2026-05-11"
+
+---
+
+# react-vite-hub
+
+Purpose: Edit the Hub UI safely — the SPA at `src/core/web/ui/` that
+serves `http://127.0.0.1:9188` and is the visual face of the entire
+coding-os system. Without this skill, agents break the build,
+introduce hydration mismatches, or invent endpoints that don't exist.
+
+Read when: editing any of:
+- `src/core/web/ui/src/**/*.{ts,tsx}` — components, pages, hooks, store.
+- `src/core/web/ui/src/lib/api-client.ts` — the API contract.
+- `src/core/web/ui/vite.config.ts`, `tailwind.config.js` — build config.
+- `src/core/web/server.py`, `src/core/web/routes/**/*.py` — when changing API shape.
+
+Skip when: editing tests (`*.test.ts`), pure docs, or `src/core/web/ui/dist/` (build output).
+
+## Stack
+
+```
+React 18 + TypeScript + Vite + TailwindCSS + Sigma.js (graph canvas)
++ Graphology (graph data) + zustand (state) + react-router-dom
++ shadcn/ui-style component primitives in src/components/
+```
+
+## Architecture (single-page, single-server)
+
+```
+http://127.0.0.1:9188
+    ├─ /api/<router>/*    ← FastAPI routes from src/core/web/routes/
+    ├─ /api/stream/events ← SSE stream from src/core/web/routes/stream.py
+    ├─ /                  ← Vite-built SPA (index.html → React)
+    └─ /assets/*          ← Vite-emitted JS/CSS bundles
+```
+
+The SPA is served by FastAPI's `StaticFiles` mount at the root. Anything
+the agent adds to the API must go in `src/core/web/routes/<area>.py`,
+include the router in `src/core/web/server.py`, and be matched by a typed
+client method in `src/lib/api-client.ts`.
+
+## Hub propagation — multi-project
+
+Each registered project is reachable via `/api/p/<slug>/*` — a thin
+proxy that targets the same routes but scoped to that project's
+`.coding-os/` state. UI uses `ProjectSwitcher` to set the slug; all
+hooks read from `useProjectStore.getState().slug` before composing
+URLs. NEVER hardcode a project path.
+
+## Hard rules
+
+### 1. URL is the source of truth
+
+`react-router-dom` URL = source of truth for "which root node is selected,"
+"which project is active," "which view." Components read URL, mutators
+call `useNavigate()` — bidirectional `useEffect` pairs cause render
+loops (TASK-117).
+
+### 2. SSE for live data
+
+Real-time hooks/cognition/board updates flow through
+`/api/stream/events` (Server-Sent Events). Use `useEventStream(channel)`
+hook in `src/lib/use-event-stream.ts`. NEVER poll.
+
+### 3. Sigma.js + Graphology
+
+Graph rendering uses Sigma.js renderer over a Graphology graph instance.
+Performance-sensitive — use:
+- `useSigma` hook for instance lifecycle (`src/features/graph/useSigma.ts`).
+- Server-paginated subgraphs via `cos_graph_export(format="json", root_uid=...)`
+  — never load the full 30K-node graph client-side.
+
+### 4. zustand stores live in `src/store/`
+
+Each domain has its own store: `graph-store.ts`, `board-store.ts`,
+`project-store.ts`. NO Redux, NO Context-only state, NO MobX. Stick
+with zustand for consistency.
+
+### 5. TailwindCSS tokens, not raw colors
+
+Use CSS custom properties (`var(--cos-border)`, `var(--cos-panel)`)
+defined in `src/index.css` + `cos-board-tokens.css`. NEVER inline hex.
+
+### 6. Type-safe API client
+
+`src/lib/api-client.ts` exposes typed methods (`api.graph.query(q)`,
+`api.board.list()`, …). Add new endpoints by extending this file.
+Components should NEVER `fetch()` directly.
+
+## Pre-edit moves
+
+1. `cos_graph_resolve("react component or feature name")` → see existing.
+2. `cos_graph_context(uid, depth=1)` → component neighbours.
+3. Check `src/lib/api-client.ts` — does the endpoint already exist?
+4. THEN edit.
+
+## Build / dev
+
+```bash
+make ui-dev      # vite dev :5173 with HMR (proxies to FastAPI :9188)
+make ui-build    # production build → src/core/web/ui/dist/
+```
+
+After a UI change: `make ui-build` to refresh the static bundle that
+the FastAPI singleton serves at `http://127.0.0.1:9188`. The dev
+server is for iteration only.
+
+## Anti-patterns
+
+- **Inline `<style>` blocks** — use Tailwind utilities or CSS variables.
+- **`useEffect` with empty deps that calls `setState`** on first render → infinite loops.
+- **Hard-coded project slug** — always read from `useProjectStore`.
+- **Loading the full graph** — paginate via `cos_graph_export` with `root_uid`.
+- **`fetch('/api/...')` directly** — extend `api-client.ts` instead.
+- **Duplicating component structure** — check `src/features/graph/` for graph utilities, `src/components/` for primitives, `src/layout/` for shells.
+
+## A11y baseline
+
+- Every interactive element has a focus ring (Tailwind `focus-visible:ring-2`).
+- Modal/dialog components use `@radix-ui/react-dialog` for keyboard trap.
+- Color contrast — verify with Lighthouse; tokens in `cos-board-tokens.css` already pass AA.
+
+## Tooling
+
+Flag Vite client-env footguns (process.env / non-VITE_ vars undefined in the build):
+`python3 scripts/check_vite_env.py src/core/web/ui/src/**/*.tsx`
+
+## See also
+
+- [assets/hub-ui-checklist.md](assets/hub-ui-checklist.md) — the Hub-UI gate (env, API contract, quality).
+- [src/core/web/ui/README.md](../../../../core/web/ui/README.md) (when present)
+- [docs/engineering/hub-architecture.md](../../../../docs/engineering/hub-architecture.md)
+- [src/core/skills/frontend-fundamentals/SKILL.md](../../../../core/skills/frontend-fundamentals/SKILL.md)
+- [src/core/skills/a11y/SKILL.md](../../../../core/skills/a11y/SKILL.md)

templates/meta/skills/react-vite-hub/assets/hub-ui-checklist.md

@@ -0,0 +1,23 @@
+<!-- domain:META | layer:asset | ssot:false | updated:2026-06-04 -->
+# Hub UI Checklist
+
+Run when editing the meta-repo Hub UI (src/core/web/ui/).
+
+## Env + build
+- [ ] Client env via `import.meta.env.VITE_*` — never `process.env` (undefined in build).
+- [ ] `python3 scripts/check_vite_env.py src/core/web/ui/src/**/*.{ts,tsx}` → `clean`.
+- [ ] `make ui-dev` (HMR :5173) for iteration; `make ui-build` to refresh `dist/`.
+
+## API contract (api-contract-discipline)
+- [ ] Every field read from a `/api/*` response verified against the producing route / `cos_*` tool — not guessed.
+- [ ] Field-name drift checked (e.g. `source_uid`/`target_uid`, not `source`/`target`).
+- [ ] Per-project calls go through `/api/p/<slug>/*`.
+
+## React/TS quality
+- [ ] `python3 ../../../../core/skills/frontend-fundamentals/scripts/check_frontend.py <files>` clean (re-render/key smells).
+- [ ] tsconfig strict (see typescript skill); Sigma.js graph updates batched.
+- [ ] zustand state minimal; no derived state duplicated.
+
+## Verify
+- [ ] `make ui-build` succeeds; the hub serves the rebuilt `dist/`.
+- [ ] `cos hub status` reports healthy symlinks.

templates/meta/skills/react-vite-hub/scripts/check_vite_env.py

@@ -0,0 +1,73 @@
+"""Flag Vite client-env footguns (process.env, non-VITE_ vars in client code).
+
+PURPOSE:      Catch env access that silently breaks in a Vite build — Vite only
+              exposes import.meta.env.VITE_* to the client; process.env and
+              non-prefixed vars are undefined at runtime.
+INPUT:        one or more UI source paths (.ts/.tsx/.js/.jsx). [--json]
+OUTPUT:       Findings (file:line) on stderr; "clean"/"N finding(s)" on stdout.
+              Exit 0 clean, 1 if findings, 2 usage.
+DEPENDENCIES: stdlib only (regex).
+NOTES:        Pure scan_text() is unit-testable. Spec: docs/engineering/hub-architecture.md;
+              craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+PROCESS_ENV = re.compile(r"\bprocess\.env\b")
+# import.meta.env.X where X is NOT VITE_-prefixed (and not the built-ins).
+BUILTINS = {"MODE", "BASE_URL", "PROD", "DEV", "SSR"}
+META_ENV = re.compile(r"import\.meta\.env\.(\w+)")
+
+
+def scan_text(text: str, *, filename: str = "?") -> list[str]:
+    findings: list[str] = []
+    for n, line in enumerate(text.splitlines(), 1):
+        stripped = line.lstrip()
+        if stripped.startswith(("//", "*", "/*")):
+            continue
+        if PROCESS_ENV.search(line):
+            findings.append(
+                f"{filename}:{n}: process.env in client code — undefined in a Vite build; "
+                "use import.meta.env.VITE_*"
+            )
+        for m in META_ENV.finditer(line):
+            var = m.group(1)
+            if var not in BUILTINS and not var.startswith("VITE_"):
+                findings.append(
+                    f"{filename}:{n}: import.meta.env.{var} not VITE_-prefixed — "
+                    "Vite won't expose it to the client"
+                )
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("files", nargs="+")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    all_findings: list[str] = []
+    for path in args.files:
+        try:
+            all_findings.extend(scan_text(Path(path).read_text(encoding="utf-8"), filename=path))
+        except FileNotFoundError:
+            print(f"error: {path} not found", file=sys.stderr)
+            return 2
+
+    for f in all_findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"findings": all_findings, "count": len(all_findings)}))
+    else:
+        print("clean" if not all_findings else f"{len(all_findings)} finding(s)")
+    return 1 if all_findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))