@minhpnq1807/contextos 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.6.4
+
+- **Project context generator:** Added `ctx doctor --fix` and `ctx setup --generate-project-context` to explicitly scaffold starter project skills and a primary workflow when a repository has rules but is missing ContextOS-ready skills/workflows. Generation is repo-scoped, does not run from `npm install`, and does not overwrite existing files unless `--force` is passed to `ctx doctor --fix`.
+
+## 0.6.3
+
+- **Launch benchmark wording:** Clarified that `ctx leaderboard --hallucination` is an offline deterministic benchmark comparing a raw heuristic baseline with ContextOS evidence-based context selection, while live agent results remain pending external CLI environments.
+- **Offline leaderboard labels:** Renamed offline leaderboard output from agent-like labels to `Raw heuristic baseline` and `ContextOS evidence benchmark` so the 10% to 80% result is not confused with a live Codex/Gemini comparison.
+- **Live leaderboard alias:** Added `ctx leaderboard --hallucination --live --agent <name>` as a launch-friendly alias for running the hallucination benchmark through one installed agent CLI. Live benchmark output now reports `OK`/`SKIPPED`/`ERROR` style statuses and supports `CONTEXTOS_<AGENT>_CMD` command templates for external wrappers.
+
 ## 0.6.2
 
 - **Live agent leaderboard:** Added `ctx leaderboard --agents codex,gemini` and `npm run leaderboard:agents` to run the hallucination benchmark through installed Codex/Gemini CLIs with timeouts and skip/error reporting for missing or unauthenticated agents.

package/README.md

@@ -1,116 +1,97 @@
 # ContextOS
 
-Runtime context router for coding agents.
+Same prompt. Same model. Different context.
 
-Rules, files, skills, workflows, and evidence: injected before the agent writes code.
+ContextOS stops coding agents from ignoring repo rules, guessing the wrong path, and reading random files.
 
 [![npm version](https://img.shields.io/npm/v/@minhpnq1807/contextos.svg)](https://www.npmjs.com/package/@minhpnq1807/contextos)
 [![CI](https://github.com/khovan123/contextOS/actions/workflows/ci.yml/badge.svg)](https://github.com/khovan123/contextOS/actions/workflows/ci.yml)
-[![ContextOS Ready](https://img.shields.io/badge/ContextOS-Ready_Gold-2ea44f)](#contextos-ready)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ```text
-WITHOUT ContextOS
-  AGENTS.md is a long static blob
-  important rules drift into the middle
-  agent starts by grepping files and misses the repo contract
+Prompt:
+Fix deployment
+
+Raw Agent:
+❌ Vercel
+❌ Docker
+❌ Railway
 
-WITH ContextOS
-  prompt -> score relevant AGENTS.md rules
-         -> inject critical rules at top and bottom
-         -> suggest files, skills, workflows
-         -> report followed / ignored / unknown
+ContextOS:
+✅ EAS
+✅ Mobile Deployment
+✅ GitHub Actions
 ```
 
-ContextOS is not another `AGENTS.md` loader. It is a runtime context router for coding agents: it chooses the task-relevant rules, files, skills, workflows, and evidence before the agent starts editing.
+ContextOS reads the repo before the agent starts: project rules, repo evidence, suggested files, skills, workflows, and post-task proof.
 
 Published package: [`@minhpnq1807/contextos`](https://www.npmjs.com/package/@minhpnq1807/contextos)
 
-## Demo
+## Hallucination Leaderboard
 
-![ContextOS demo: same prompt, different repo, correct skills](docs/demo/same-prompt-different-context.gif)
+Offline deterministic benchmark:
 
-Same prompt. Same model. Different context.
+| System | Correct context choice |
+| --- | ---: |
+| Raw heuristic baseline | 10.0% |
+| ContextOS evidence benchmark | 80.0% |
 
 ```bash
-ctx skills doctor -- "fix deployed"
+ctx leaderboard --hallucination
 ```
 
-| Repo evidence | Expected route |
-| --- | --- |
-| `eas.json`, `expo`, `react-native` | `eas`, `mobile-deployment`, `github-actions-ci-cd` |
-| `vercel.json`, `next`, GitHub workflow | `vercel-deployment`, `github-actions-ci-cd`, `env-secret-management` |
-| ContextOS repo with no app deploy evidence | no deployment skill selected |
-
-More 10-second demos:
-
-| Demo | GIF |
-| --- | --- |
-| AGENTS.md Lost In The Middle | [docs/demo/agents-lost-middle.gif](docs/demo/agents-lost-middle.gif) |
-| ContextOS Ready Gold | [docs/demo/contextos-ready.gif](docs/demo/contextos-ready.gif) |
+This means ContextOS improves deterministic context routing from 10% to 80% on the offline hallucination task set. It does not claim ContextOS beats Codex, Gemini, Claude Code, or Cursor in live runs.
 
-Regenerate the GIFs from real local `ctx` command output:
+Live agent benchmark support exists, but results are pending an external environment with working CLI auth/session access:
 
 ```bash
-npm run demo:capture
+ctx leaderboard --hallucination --live --agent codex
+ctx leaderboard --hallucination --live --agent gemini
 ```
 
-## Agent Hallucination Benchmark
+If a CLI cannot run in the current environment, the command reports `SKIPPED` or an agent error instead of blocking launch.
 
-Generic agents often guess deployment tooling from the prompt alone:
+Live benchmark tracking:
 
-```text
-Prompt: Fix deployment
-Raw agent guess: Vercel, Docker, Railway
-```
-
-ContextOS routes from project evidence instead:
-
-```text
-Detected evidence:
-- eas.json
-- expo dependency
-- GitHub workflow
-
-Selected skills:
-- eas
-- mobile-deployment
-- github-actions-ci-cd
-```
+- [Run Codex live benchmark](https://github.com/khovan123/contextOS/issues/1)
+- [Run Claude Code live benchmark](https://github.com/khovan123/contextOS/issues/3)
+- [Run Gemini CLI live benchmark](https://github.com/khovan123/contextOS/issues/4)
+- [Run Cursor live benchmark](https://github.com/khovan123/contextOS/issues/2)
 
-That is the core launch demo: same prompt, same model, different repo context, correct skills.
+## Why People Star ContextOS
 
-Skill Router internal fixture benchmark:
+- Agents ignore `AGENTS.md`.
+- Agents choose the wrong deployment path.
+- Agents grep random files before understanding the repo.
+- ContextOS fixes all three before coding starts.
 
-| Metric | Result |
-| --- | ---: |
-| Cases | 52 |
-| Top-1 Accuracy | 94.2% |
-| Top-3 Recall | 94.2% |
-| False Positive Rate | 0.0% |
-| Confidence Calibration | 100.0% |
-| Negative Gate Accuracy | 100.0% |
-
-This is an internal fixture benchmark, not an external real-world benchmark. It is designed to prove the router behavior across controlled Expo/EAS, Next/Vercel, Docker, Railway/Render, Firebase, auth, database, testing, mobile, and adversarial negative-gate cases.
+## Demo
 
-Hallucination leaderboard:
+![ContextOS demo: same prompt, different repo, correct skills](docs/demo/same-prompt-different-context.gif)
 
 ```bash
-ctx leaderboard --hallucination
+ctx skills doctor -- "fix deployed"
 ```
 
-Current local result across 20 fixture tasks and 12 repo contexts:
+| Repo evidence | What ContextOS tells the agent |
+| --- | --- |
+| `eas.json`, `expo`, `react-native` | `eas`, `mobile-deployment`, `github-actions-ci-cd` |
+| `vercel.json`, `next`, GitHub workflow | `vercel-deployment`, `github-actions-ci-cd`, `env-secret-management` |
+| ContextOS repo with no app deploy evidence | no deployment skill selected |
 
-| System | Correct Skill |
-| --- | ---: |
-| Raw Agent | 10.0% |
-| ContextOS + Codex | 80.0% |
+More 10-second demo:
+
+| Demo | GIF |
+| --- | --- |
+| AGENTS.md Lost In The Middle | [docs/demo/agents-lost-middle.gif](docs/demo/agents-lost-middle.gif) |
+
+## What The Agent Sees
 
-Example hook context injected before the agent works:
+ContextOS injects a compact brief before the agent works:
 
 ```text
 ## Critical ContextOS rules
-- IMPORTANT: This project has a knowledge graph. ALWAYS use code-review-graph MCP tools before Grep/Glob/Read.
+- IMPORTANT: This project has a knowledge graph. Use it before broad file search.
 - Use `query_graph` pattern="tests_for" to check coverage.
 
 ## Suggested files to check
@@ -129,9 +110,30 @@ ContextOS report
 Efficiency: 100%
 Injected rules: 8
 Rule outcomes: 8 followed, 0 ignored, 0 unknown
-Runtime telemetry: code-review-graph, code-review-graph.query_graph_tool
+Runtime evidence: project graph was used before file search
 ```
 
+Regenerate the GIFs from real local `ctx` command output:
+
+```bash
+npm run demo:capture
+```
+
+## Internal Benchmark
+
+Skill selection fixture benchmark:
+
+| Metric | Result |
+| --- | ---: |
+| Cases | 52 |
+| Top-1 Accuracy | 94.2% |
+| Top-3 Recall | 94.2% |
+| False Positive Rate | 0.0% |
+| Confidence Calibration | 100.0% |
+| Negative Gate Accuracy | 100.0% |
+
+This is an internal fixture benchmark, not an external real-world benchmark. It is designed to prove that ContextOS changes its suggestions from repo evidence across controlled Expo/EAS, Next/Vercel, Docker, Railway/Render, Firebase, auth, database, testing, mobile, and adversarial negative cases.
+
 ## Quick Install
 
 Install in 30 seconds:
@@ -148,6 +150,13 @@ Scriptable setup:
 ```bash
 ctx setup --yes
 ctx setup --yes --agents codex,claude,agy
+ctx setup --yes --generate-project-context
+```
+
+If `ctx doctor` reports missing project skills/workflows, generate starter project context explicitly:
+
+```bash
+ctx doctor --fix
 ```
 
 No global install:
@@ -172,37 +181,23 @@ ctx install agy
 
 Restart the agent after setup. Then use the agent normally.
 
-## Why
-
-Developers put real operating instructions in `AGENTS.md`: use this graph tool before reading files, run these tests, follow this architecture boundary, avoid this migration path.
-
-The problem is not that agents cannot read `AGENTS.md`. The problem is that large context windows bury the important rule in the middle, where attention is weak. ContextOS turns a static rules file into task-aware runtime context.
-
-The next visible demo is not another feature. It is showing the pain in a few seconds:
-
-```text
-Raw agent: guesses from the prompt.
-ContextOS: routes from repo evidence.
-```
-
 ## What ContextOS Does
 
-| Layer | What happens |
+| Agent failure | ContextOS behavior |
 | --- | --- |
-| Hooks | Codex, Claude Code, and Antigravity hooks run before/after each task. |
-| Scoring | Local MiniLM embeddings plus heuristics rank AGENTS.md rules by the prompt. |
-| Injection | Critical rules are placed with primacy + recency, not buried in the middle. |
-| Discovery | Relevant files, skills, and workflows are suggested before work starts. |
-| Sync | Rules/MCP via Ruler, skills via skillshare, workflows via ContextOS. |
-| Evidence | Stop hooks persist `followed`, `ignored`, `unknown`, and runtime telemetry for explicit reports. |
+| Ignores project rules | Shows the relevant rules at the start of the task. |
+| Picks the wrong tool or deployment path | Suggests skills only when the repo has supporting evidence. |
+| Reads random files first | Suggests the likely files and workflows before exploration starts. |
+| Claims compliance without proof | Reports which rules were followed, ignored, or unknown after the task. |
+| Needs to work across agents | Supports Codex, Claude Code, and Antigravity with the same project context. |
 
 ## Comparison
 
 | Approach | What it gives the agent | Main gap |
 | --- | --- | --- |
 | Plain `AGENTS.md` | Static repo instructions. | Important rules get buried or ignored when the task changes. |
-| Generic RAG | Semantically related files or snippets. | It usually does not route skills/workflows or prove rule compliance. |
-| ContextOS | Task-routed rules, files, skills, workflows, and evidence. | Requires local setup and warm indexes for best results. |
+| Generic RAG | Related files or snippets. | It usually does not choose skills/workflows or prove rule compliance. |
+| ContextOS | Task-specific rules, files, skills, workflows, and evidence. | Requires local setup and prepared indexes for best results. |
 
 ## Safety Model
 
@@ -212,20 +207,20 @@ ContextOS is designed to be OSS-friendly and low-friction:
 | --- | --- |
 | Standalone by default | `ctx setup` works without `code-review-graph`, `codegraph`, or `agent-memory`. |
 | Optional adapters | Graph and memory backends add signal when available; missing adapters contribute score `0`. |
-| Fail-open hooks | Prompt hooks return local context or nothing instead of blocking the agent when MCP, embeddings, graph, or memory is unavailable. |
+| Fail-open hooks | Prompt hooks return local context or nothing instead of blocking the agent when optional runtime pieces are unavailable. |
 | Local-only telemetry | Reports, prompt history, evidence, and telemetry stay under `~/.ctx/contextos/`. |
-| No hook network calls | Prompt and stop hooks do not call external services. Install/warm commands may download the local embedding model when explicitly run. |
+| No hook network calls | Prompt and stop hooks do not call external services. Install/warm commands may prepare local indexes when explicitly run. |
 | No postinstall surprise | `npm install` only installs the CLI. Setup runs only when you call `ctx setup`. |
 
-Positioning: ContextOS works standalone and gets smarter when graph or memory adapters are available.
+Positioning: ContextOS works standalone and gets smarter when project graph or memory adapters are available.
 
 ## Roadmap
 
-ContextOS is not heading toward a dashboard-first product. The next work is focused on making the existing local runtime more visible and reusable:
+ContextOS is not heading toward a dashboard-first product. The next work is focused on making the existing local behavior more visible and reusable:
 
 | Next | Why |
 | --- | --- |
-| Hallucination Leaderboard | Compare raw agent guesses vs ContextOS evidence-routed recommendations across the same repos and tasks. |
+| Hallucination Leaderboard | Compare raw agent guesses vs ContextOS evidence-based recommendations across the same repos and tasks. |
 | Agent Replay | Turn telemetry into a readable post-task narrative: prompt, selected skills, followed rules, suggested files, touched files, efficiency. |
 | Community Skill Packs | Let contributors PR ContextOS-ready skills with triggers, evidence, negative gates, and workflows before building a larger hub. |
 | ContextOS Ready | Define a repository readiness badge for AGENTS.md, skills, workflows, and evidence quality. |
@@ -237,11 +232,11 @@ See [docs/roadmap.md](docs/roadmap.md) for the current roadmap notes.
 
 ContextOS starts the community loop with [`community-skills/`](community-skills/) instead of a hosted marketplace. The seed packs are `eas`, `vercel`, `prisma`, `redis`, `oauth-google`, and `jwt-auth`.
 
-Each pack contains a model-visible `SKILL.md` plus `skill.yaml` routing metadata with prompt triggers, project evidence, negative triggers, and a short workflow. Contributors can PR new packs by copying [`community-skills/_template/`](community-skills/_template/).
+Each pack contains a model-visible `SKILL.md` plus `skill.yaml` metadata with prompt triggers, project evidence, negative triggers, and a short workflow. Contributors can PR new packs by copying [`community-skills/_template/`](community-skills/_template/).
 
 ## ContextOS Ready
 
-`ctx doctor` scores whether a repository is ready for ContextOS-style agent routing:
+`ctx doctor` scores whether a repository is ready for ContextOS-style agent guidance:
 
 ```bash
 ctx doctor
@@ -267,14 +262,16 @@ The score checks project `AGENTS.md` rules, project skill packs under `.codex/sk
 | `ctx setup` | Recommended first-run install flow. |
 | `ctx debug -- "Recheck authen flow"` | Preview what ContextOS would inject. |
 | `ctx doctor` | Score repository readiness for the `ContextOS Ready` badge. |
+| `ctx doctor --fix` | Generate starter project skills and workflow when the repo is missing them. |
 | `ctx report` | Show the last task's compliance summary. |
 | `ctx evidence` | Show why each rule was marked followed/ignored/unknown. |
 | `ctx stats` | Show workspace-level usage and effectiveness metrics. |
 | `ctx benchmark -- "task"` | Compare raw AGENTS.md ordering vs ContextOS scheduling. |
-| `ctx benchmark --skills` | Run the Skill Router eval benchmark. |
-| `ctx leaderboard --hallucination` | Compare raw prompt-only guesses vs ContextOS routing. |
-| `ctx leaderboard --agents codex,gemini` | Run the live CLI leaderboard when Codex/Gemini credentials are available. |
-| `ctx sync --rules` | Sync AGENTS/Ruler/MCP config across agents. |
+| `ctx benchmark --skills` | Run the skill selection eval benchmark. |
+| `ctx leaderboard --hallucination` | Run the offline deterministic hallucination benchmark. |
+| `ctx leaderboard --hallucination --live --agent codex` | Run the live CLI benchmark when agent auth/session is available. |
+| `ctx leaderboard --agents codex,gemini` | Legacy live CLI leaderboard form. |
+| `ctx sync --rules` | Sync project rules across agents. |
 | `ctx sync --skills` | Sync skills across agents through skillshare. |
 | `ctx sync --workflows` | Sync workflow markdown across Claude/Codex/Antigravity. |
 
@@ -283,7 +280,7 @@ The score checks project `AGENTS.md` rules, project skill packs under `.codex/sk
 1. Start in a repo with an `AGENTS.md` that contains a rule like:
 
 ```text
-Always use code-review-graph MCP tools before reading files.
+Always use the project graph before reading files.
 ```
 
 2. Install:
@@ -587,19 +584,22 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx install --copy` | Copies only the plugin payload to `$CODEX_HOME/plugins/ctx`. | Legacy local development or manual plugin experiments. | Does not sync the active marketplace, rebuild indexes, register MCP, or install global hooks. Prefer `ctx refresh` for active local updates. |
 | `ctx setup` | Runs the first-run setup wizard. | You want the recommended onboarding flow after `npm install -g @minhpnq1807/contextos`. | Installs selected agents, optionally syncs Ruler rules/MCP and skillshare skills, asks which prompt sections to show, then prints next steps. |
 | `ctx setup --yes` | Runs setup with defaults non-interactively. | You want scriptable Codex setup. | Uses `codex`, enables injection, syncs rules, syncs skills, skips interactive community-skill installation when no TTY is available, and passes `--yes` to dependency setup prompts. Use `--agents codex,claude,agy` for multi-agent setup. |
+| `ctx setup --generate-project-context` | Generates starter project skills and workflow during setup. | Your repo has rules but `ctx doctor` reports missing skills/workflows. | Creates `.codex/skills/<detected-skill>/SKILL.md`, matching `skill.yaml`, and `.codex/workflows/primary.md` without overwriting existing files. |
 | `ctx setup --agents <list>` | Runs setup for selected agents. | You want only part of the default set. | Accepts comma-separated `codex`, `claude`, `agy`, or `antigravity`. |
 | `ctx setup --no-rules` | Skips Ruler sync during setup. | You only want hooks/MCP install and maybe skill sync. | Does not run `ctx sync --rules`. |
 | `ctx setup --no-skills` | Skips skillshare sync during setup. | You do not want shared skills configured. | Does not run `ctx sync --skills`. |
 | `ctx setup --quiet` | Runs setup in measurement-only mode. | You want reports/stats without visible injected prompt context. | Installs hooks with prompt context injection disabled. |
 | `ctx debug -- "task"` | Runs the scheduler locally for a fake prompt. | You want to see which AGENTS.md rules and files ContextOS would inject before using Codex. | Prints rule scores, scoring reasons, suggested files, and final `additionalContext`. |
 | `ctx doctor` | Scores repository ContextOS readiness. | You want to add or verify a `ContextOS Ready` badge. | Prints Rules, Skills, Workflows, Overall tier, evidence, and next recommendations. |
+| `ctx doctor --fix` | Generates starter ContextOS project context. | `ctx doctor` says skills/workflows are missing and you want explicit local scaffolding. | Detects package/config evidence, creates up to three starter project skills plus `.codex/workflows/primary.md`, then prints the updated readiness score. |
 | `ctx report` | Shows the last Stop-hook compliance report for the current workspace. | An agent task has finished and you want the summary again. | Prints sectioned tables for summary, rule outcomes, suggested files, and runtime telemetry from `~/.ctx/contextos/workspaces/<workspace-id>/last-report.json`. |
 | `ctx evidence` | Shows detailed evidence behind the last report for the current workspace. | You want to inspect why a rule was marked `followed`, `ignored`, `unknown`, or `unmeasurable`. | Prints a compact evidence table plus per-rule detail tables. |
 | `ctx stats` | Shows aggregate runtime metrics for the current workspace. | You want to know whether ContextOS is active and useful over time. | Prints sectioned tables for prompt/report counts, injection rate, efficiency, rule outcomes, hook events, last prompt, and last report. |
 | `ctx benchmark -- "task"` | Compares baseline AGENTS.md ordering with ContextOS task-aware scheduling. | You want a before/after signal for lost-in-the-middle risk. | Prints tables for parsed/actionable/filtered rules, baseline middle-risk, scheduled high/mid rules, recency reminder status, and top scored rules. |
 | `ctx benchmark --skills` | Runs the Skill Router eval benchmark. | You want evidence for skill routing accuracy and negative gates. | Prints top-1 accuracy, top-3 recall, false positive rate, confidence calibration, and negative gate accuracy across `eval/skill-routing` fixtures. |
-| `ctx leaderboard --hallucination` | Compares raw prompt-only skill guesses with ContextOS evidence routing. | You want launch evidence for the hallucination problem. | Runs 20 fixture tasks across 10+ repo contexts and prints Raw Agent vs ContextOS correctness plus sample failures. |
-| `ctx leaderboard --agents codex,gemini` | Runs the same benchmark shape through installed agent CLIs. | You want real agent output instead of the deterministic raw baseline. | Calls `codex exec` in read-only mode and the local Gemini CLI with timeouts; missing or unauthenticated CLIs are reported as skipped/errors instead of blocking. |
+| `ctx leaderboard --hallucination` | Runs the offline deterministic hallucination benchmark. | You want launch evidence for the wrong-context problem without depending on external agent auth. | Runs 20 fixture tasks across 10+ repo contexts and prints Raw heuristic baseline vs ContextOS evidence benchmark plus sample failures. |
+| `ctx leaderboard --hallucination --live --agent codex` | Runs the hallucination benchmark through one installed agent CLI. | You want real agent output and have CLI auth/session available. | Calls the selected CLI with timeouts; missing, blocked, or unauthenticated CLIs are reported as skipped/errors instead of blocking. |
+| `ctx leaderboard --agents codex,gemini` | Legacy live CLI leaderboard form. | You want to run multiple live agents at once. | Equivalent live-agent benchmark shape for comma-separated CLIs. |
 | `ctx sync --rules` | Syncs project rules and MCP servers through Ruler. | You want Codex, Claude Code, and Antigravity to share one project rule/MCP source of truth. | Ensures `.ruler/ruler.toml`, injects `ctx-mcp`, imports existing MCP servers from Codex and project `.mcp.json`, runs `ruler apply --agents codex,claude,antigravity`, mirrors MCP servers to Antigravity MCP configs, and verifies generated config. |
 | `ctx sync --rules --agents <list>` | Syncs only selected agents through Ruler. | You want to update one or two agents without touching the others. | Accepts comma-separated values such as `codex`, `claude`, `agy`, `antigravity`, or `codex,claude,agy`; `agy` is normalized to Ruler's `antigravity`. |
 | `ctx sync --rules --dry-run` | Previews Ruler sync without writing files or running apply. | You want to inspect behavior before changing project config. | Prints the same flow with dry-run status. |
@@ -664,7 +664,7 @@ These files are local telemetry only. Hooks do not make network calls.
 
 ## Project Understanding
 
-ContextOS works standalone. The core path is local rules, file embeddings, import graph expansion, skill routing, workflow routing, and evidence capture.
+ContextOS works standalone. The default path is local project rules, prepared file indexes, project skills, workflows, and evidence capture.
 
 Project graph and memory backends are optional adapters:
 
@@ -676,26 +676,24 @@ Project graph and memory backends are optional adapters:
 
 ContextOS does not require `code-review-graph`, `codegraph`, or `agent-memory` to install or run. It gets smarter when those backends are available; when they are missing, the adapter scores stay at zero and the hook continues with local context.
 
-For file suggestions, ContextOS now runs a local RAG-style retrieval pass:
+For file suggestions, ContextOS uses prepared local indexes:
 
 ```text
 prompt
-  -> UserPromptSubmit hook calls ctx-mcp bridge
-  -> ctx-mcp reads AGENTS.md and scores rules with local MiniLM
-  -> query the persisted file-vector index in embeddings.db for semantic file candidates
-  -> expand candidates through relative import graph links
-  -> optionally query code-review-graph semantic_search_nodes with seed entity names
-  -> merge and deduplicate semantic, import-graph, and optional graph matches
-  -> inject top suggested files with graph evidence reasons
+  -> read task-relevant AGENTS.md rules
+  -> suggest prepared file candidates
+  -> expand nearby imports
+  -> add optional project-graph matches when available
+  -> inject a compact list of files to check
 ```
 
-This keeps the hook fast and local while still using graph semantics when available. The graph search path is visible in runtime data through file reasons such as `graph:content-moderation.service`. When no graph adapter is available, file suggestions still use local file vectors and import graph expansion.
+This keeps the hook fast and local while still using project graph signal when available. When no graph adapter is available, file suggestions still use local file indexes and import expansion.
 
-Prompt scoring does not walk the repository for file candidates or import expansion. `ctx install` and `ctx embeddings warm` rebuild the persisted file-vector index and one-hop import adjacency index by walking source paths once; prompt hooks query those indexes directly. Rules, files, skills, and workflows are scored concurrently with `Promise.all()`.
+Prompt-time file suggestions do not walk the repository. `ctx install` and `ctx embeddings warm` rebuild the file index and one-hop import adjacency by walking source paths once; prompt hooks query those prepared indexes directly. Rules, files, skills, and workflows are resolved concurrently.
 
 `ctx embeddings warm` automatically refreshes the active Codex marketplace payload before rebuilding indexes. Use `ctx refresh` when you want the same marketplace sync plus install-style file, skill, import, and code-review-graph embedding refresh in one command.
 
-If a prompt has no usable context candidates, the hook fails open without emitting an empty `hook context` block, records `emptyContextReason` in the workspace runtime file, and starts a detached `autowarm` rebuild with a cooldown. That background rebuild refreshes file vectors, skill/workflow vectors, import adjacency, and available code-review-graph node embeddings for the next prompt while keeping repository walking out of the current prompt hot path.
+If a prompt has no usable context candidates, the hook fails open without emitting an empty `hook context` block, records `emptyContextReason` in the workspace runtime file, and starts a detached `autowarm` rebuild with a cooldown. That background rebuild refreshes prepared indexes for the next prompt while keeping repository walking out of the current prompt path.
 
 Use `ctx --config` to choose which prompt sections ContextOS injects and how many suggestions each section may show. Interactive `ctx setup` includes the same section picker and limit prompts, while `ctx setup --yes` keeps the current saved config for automation. The panel supports multiple selection with `Space` and persists the global choice in `~/.ctx/contextos/output-config.json`. Defaults are five suggested files, five skills, and five workflows; caps are 20 files, 10 skills, and 5 workflows. Disabling rules hides both critical and additional relevant rule sections; compliance metadata remains available for reports.
 

package/bin/ctx.js

@@ -44,6 +44,7 @@ import { fetchSkillsForAgents, printSkillRecommendations, getAllLibraries, getIn
 import { invalidateCtxMcpSocket } from "../plugins/ctx/lib/ctx-mcp-client.js";
 import { runPrefixedCommand } from "../plugins/ctx/lib/shell-runner.js";
 import { formatContextOSReady, inspectContextOSReady } from "../plugins/ctx/lib/certification.js";
+import { formatProjectContextGeneration, generateProjectContext } from "../plugins/ctx/lib/project-context-generator.js";
 
 /**
  * Run a shell command with all output lines prefixed by │  
@@ -189,17 +190,22 @@ Usage:
   ctx setup                                         Interactive full setup wizard
   ctx setup --yes                                   Auto-confirm all setup prompts
   ctx setup --agents <names>                        Pre-select agents to install
+  ctx setup --generate-project-context              Generate starter project skills/workflow
   ctx setup --no-rules                              Skip AGENTS.md rule sync
   ctx setup --no-skills                             Skip skill sync
   ctx setup --quiet                                 Quiet mode (minimal output)
   ctx debug -- "task"                               Debug a task with ContextOS tracing
   ctx doctor                                       Score repository ContextOS readiness
+  ctx doctor --fix                                 Generate starter project skills/workflow
+  ctx doctor --fix --force                         Regenerate starter project context files
   ctx report                                        Show last ContextOS compliance report
   ctx evidence                                      Show evidence from last report
   ctx stats                                         Show workspace statistics
   ctx benchmark -- "task"                           Benchmark workspace for a task
   ctx benchmark --skills                            Run skill routing eval benchmark
-  ctx leaderboard --hallucination                   Compare raw agent guesses vs ContextOS routing
+  ctx leaderboard --hallucination                   Run offline deterministic hallucination benchmark
+  ctx leaderboard --hallucination --live --agent codex
+                                                    Run hallucination benchmark through one live CLI
   ctx leaderboard --agents codex,gemini             Run live CLI leaderboard for installed agents
   ctx sync --rules                                  Sync AGENTS.md rules to all agents
   ctx sync --rules --agents <names>                 Sync rules to specific agents only
@@ -252,6 +258,18 @@ function normalizeInstallAgent(agent) {
   if (normalized === "antigravity") return "agy";
   return normalized;
 }
+
+function leaderboardAgentsFromArgs(args) {
+  const agentIndex = args.indexOf("--agent");
+  const agentsIndex = args.indexOf("--agents");
+  const index = agentIndex >= 0 ? agentIndex : agentsIndex;
+  if (index < 0) return [];
+  return String(args[index + 1] || "")
+    .split(",")
+    .map((agent) => agent.trim())
+    .filter(Boolean);
+}
+
 /**
  * Intercept console.log from an async fn,
  * printing each line immediately with "│  " prefix for real-time feedback.
@@ -866,6 +884,22 @@ async function setup({ args = [], cwd = process.cwd() } = {}) {
     });
   }
 
+  if (interactive && !options.generateProjectContext) {
+    const readiness = inspectContextOSReady({ cwd });
+    if (readiness.skills.score < 50 || readiness.workflows.score < 50) {
+      const rl = readline.createInterface({ input, output });
+      try {
+        options.generateProjectContext = await askSetupYesNo(
+          rl,
+          "Generate starter project skills and workflow?",
+          true
+        );
+      } finally {
+        rl.close();
+      }
+    }
+  }
+
   console.log("");
   console.log("◇ Ready to setup:");
   for (const line of setupSummaryLines({
@@ -878,6 +912,13 @@ async function setup({ args = [], cwd = process.cwd() } = {}) {
 
   if (!options.agents.length) throw new Error("No agents selected. Use --agents codex,claude,antigravity,copilot.");
 
+  if (options.generateProjectContext) {
+    console.log("◇ Generating starter project context...");
+    const generated = generateProjectContext({ cwd });
+    for (const line of formatProjectContextGeneration(generated).split("\n")) console.log(`│  ${line}`);
+    console.log("");
+  }
+
   for (const agent of options.agents) {
     console.log(`◇ Setting up ${agent}...`);
     await streamSetupOutput(() => install({ agent, copy: false }));
@@ -1008,7 +1049,14 @@ try {
     if (!task.trim()) throw new Error('Usage: ctx debug -- "task"');
     await debug(task);
   } else if (command === "doctor") {
-    console.log(formatContextOSReady(inspectContextOSReady({ cwd: process.cwd() })));
+    if (args.includes("--fix")) {
+      const generated = generateProjectContext({ cwd: process.cwd(), force: args.includes("--force") });
+      console.log(formatProjectContextGeneration(generated));
+      console.log("");
+      console.log(formatContextOSReady(inspectContextOSReady({ cwd: process.cwd() })));
+    } else {
+      console.log(formatContextOSReady(inspectContextOSReady({ cwd: process.cwd() })));
+    }
   } else if (command === "refresh") {
     await refresh();
   } else if (command === "autowarm") {
@@ -1039,7 +1087,17 @@ try {
     console.log(formatBenchmark(benchmarkWorkspace({ cwd: process.cwd(), task })));
     }
   } else if (command === "leaderboard") {
-    if (args.includes("--hallucination")) {
+    if (args.includes("--hallucination") && args.includes("--live")) {
+      const agents = leaderboardAgentsFromArgs(args);
+      const limitIndex = args.indexOf("--limit");
+      const timeoutIndex = args.indexOf("--timeout-ms");
+      console.log(formatAgentLeaderboard(runAgentLeaderboard({
+        rootDir,
+        agents: agents.length ? agents : undefined,
+        caseLimit: limitIndex >= 0 ? Number(args[limitIndex + 1]) : undefined,
+        timeoutMs: timeoutIndex >= 0 ? Number(args[timeoutIndex + 1]) : undefined
+      })));
+    } else if (args.includes("--hallucination")) {
       console.log(formatHallucinationLeaderboard(await runHallucinationLeaderboard({ rootDir })));
     } else if (args.includes("--agents")) {
       const index = args.indexOf("--agents");
@@ -1053,7 +1111,7 @@ try {
         timeoutMs: timeoutIndex >= 0 ? Number(args[timeoutIndex + 1]) : undefined
       })));
     } else {
-      throw new Error("Usage: ctx leaderboard --hallucination OR ctx leaderboard --agents codex,gemini");
+      throw new Error("Usage: ctx leaderboard --hallucination OR ctx leaderboard --hallucination --live --agent codex OR ctx leaderboard --agents codex,gemini");
     }
   } else if (command === "skills") {
     if (args[1] === "doctor") {

package/eval/hallucination/run-agent-leaderboard.js

@@ -29,7 +29,8 @@ export function runAgentLeaderboard({
   const systems = [];
 
   for (const agent of agents) {
-    const binary = findBinary(agent);
+    const template = agentCommandTemplate(agent);
+    const binary = template ? template.split(/\s+/).filter(Boolean)[0] : findBinary(agent);
     if (!binary) {
       systems.push({ name: agent, status: "skipped", reason: "binary not found", rows: [], correctRate: 0 });
       continue;
@@ -71,7 +72,7 @@ export function formatAgentLeaderboard(result) {
   ];
   for (const system of result.systems) {
     const score = system.status === "ok" ? percent(system.correctRate) : system.reason;
-    lines.push(`${system.name.padEnd(8)}  ${system.status.padEnd(8)}  ${score}`);
+    lines.push(`${system.name.padEnd(8)}  ${system.status.toUpperCase().padEnd(8)}  ${score}`);
   }
   lines.push("", "Cases:");
   for (const system of result.systems) {
@@ -123,6 +124,8 @@ function runAgentCase({ agent, binary, testCase, skillIds, timeoutMs, rootDir })
 }
 
 function agentArgs({ agent, cwd, prompt }) {
+  const genericTemplate = agentCommandTemplate(agent);
+  if (genericTemplate) return expandTemplate(genericTemplate, { cwd, prompt }).slice(1);
   if (agent === "codex") {
     return [
       "exec",
@@ -140,6 +143,11 @@ function agentArgs({ agent, cwd, prompt }) {
   return [prompt];
 }
 
+function agentCommandTemplate(agent) {
+  const envKey = `CONTEXTOS_${String(agent || "").toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_CMD`;
+  return process.env[envKey] || "";
+}
+
 function buildPrompt({ task, skillIds }) {
   return [
     "You are evaluating a repository for a coding-agent skill router benchmark.",
@@ -180,6 +188,11 @@ function findBinary(name) {
   for (const candidate of candidates) {
     if (fs.existsSync(candidate)) return candidate;
   }
+  for (const dir of String(process.env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, safeName);
+    if (fs.existsSync(candidate)) return candidate;
+  }
   for (const command of [
     `command -v ${safeName}`,
     `source ~/.profile >/dev/null 2>&1 || true; source ~/.bashrc >/dev/null 2>&1 || true; command -v ${safeName}`

package/eval/hallucination/run-leaderboard.js

@@ -41,8 +41,8 @@ export async function runHallucinationLeaderboard({
     caseCount: selectedCases.length,
     repoCount: new Set(selectedCases.map((row) => row.fixture)).size,
     systems: [
-      summarizeSystem("Raw Agent", rawRows),
-      summarizeSystem("ContextOS + Codex", contextRows)
+      summarizeSystem("Raw heuristic baseline", rawRows),
+      summarizeSystem("ContextOS evidence benchmark", contextRows)
     ],
     rows: selectedCases.map((testCase) => ({
       prompt: testCase.prompt,
@@ -60,11 +60,11 @@ export function formatHallucinationLeaderboard(result) {
     `Repos: ${result.repoCount}`,
     `Tasks: ${result.caseCount}`,
     "",
-    "System              Correct Skill",
-    "------------------  -------------"
+    "System                        Correct Context",
+    "----------------------------  ---------------"
   ];
   for (const system of result.systems) {
-    lines.push(`${system.name.padEnd(18)}  ${percent(system.correctRate)}`);
+    lines.push(`${system.name.padEnd(28)}  ${percent(system.correctRate)}`);
   }
   lines.push("", "Sample failures:");
   const failures = result.rows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Inject task-relevant AGENTS.md rules into Codex through plugin hooks.",
   "author": {
     "name": "ContextOS"

package/plugins/ctx/lib/certification.js

@@ -68,6 +68,9 @@ export function formatContextOSReady(result) {
   if (next.length) {
     lines.push("", "Next:");
     for (const item of [...new Set(next)].slice(0, 5)) lines.push(`- ${item}`);
+    if (result.skills.score < 50 || result.workflows.score < 50) {
+      lines.push("- Run `ctx doctor --fix` to generate starter project skills and workflow.");
+    }
   }
 
   return lines.join("\n");

package/plugins/ctx/lib/project-context-generator.js

@@ -0,0 +1,389 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { clearSkillScanCache } from "./skill-discoverer.js";
+
+const STARTER_SKILL_LIMIT = 3;
+
+export function generateProjectContext({ cwd = process.cwd(), force = false } = {}) {
+  const root = findProjectRoot(cwd);
+  const profile = detectProjectProfile(root);
+  const skills = selectStarterSkills(profile).slice(0, STARTER_SKILL_LIMIT);
+  const created = [];
+  const skipped = [];
+
+  for (const skill of skills) {
+    const dir = path.join(root, ".codex", "skills", skill.id);
+    const skillPath = path.join(dir, "SKILL.md");
+    const yamlPath = path.join(dir, "skill.yaml");
+    fs.mkdirSync(dir, { recursive: true });
+    writeFile({ filePath: skillPath, content: renderSkillMarkdown(skill), force, created, skipped });
+    writeFile({ filePath: yamlPath, content: renderSkillYaml(skill), force, created, skipped });
+  }
+
+  const workflowPath = path.join(root, ".codex", "workflows", "primary.md");
+  fs.mkdirSync(path.dirname(workflowPath), { recursive: true });
+  writeFile({
+    filePath: workflowPath,
+    content: renderPrimaryWorkflow(profile, skills),
+    force,
+    created,
+    skipped
+  });
+  clearSkillScanCache();
+
+  return {
+    root,
+    profile,
+    skills: skills.map((skill) => skill.id),
+    created,
+    skipped
+  };
+}
+
+export function formatProjectContextGeneration(result) {
+  const lines = [
+    "Project context generated",
+    "",
+    `Root: ${result.root}`,
+    `Detected: ${result.profile.summary}`,
+    `Skills: ${result.skills.join(", ") || "(none)"}`,
+    "",
+    "Created:"
+  ];
+  if (result.created.length) {
+    for (const filePath of result.created) lines.push(`- ${path.relative(result.root, filePath)}`);
+  } else {
+    lines.push("- none");
+  }
+  if (result.skipped.length) {
+    lines.push("", "Skipped existing files:");
+    for (const filePath of result.skipped) lines.push(`- ${path.relative(result.root, filePath)}`);
+  }
+  lines.push("", "Next:");
+  lines.push("- Review generated skills/workflow and edit project-specific wording.");
+  lines.push("- Run: ctx doctor");
+  lines.push("- Run: ctx debug -- \"your task\"");
+  return lines.join("\n");
+}
+
+function detectProjectProfile(root) {
+  const packageFiles = findPackageJsonFiles(root);
+  const packages = packageFiles.map((filePath) => ({
+    filePath,
+    json: safeJson(filePath)
+  })).filter((item) => item.json);
+  const dependencies = new Set();
+  const scripts = new Set();
+  for (const item of packages) {
+    for (const section of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+      for (const name of Object.keys(item.json[section] || {})) dependencies.add(name);
+    }
+    for (const name of Object.keys(item.json.scripts || {})) scripts.add(name);
+  }
+  const files = new Set([
+    ...findExisting(root, [
+      "eas.json",
+      "app.json",
+      "app.config.js",
+      "app.config.ts",
+      "vercel.json",
+      "Dockerfile",
+      "docker-compose.yml",
+      "compose.yml",
+      "railway.json",
+      "render.yaml",
+      "firebase.json",
+      "prisma/schema.prisma",
+      "jest.config.js",
+      "jest.config.ts",
+      "playwright.config.ts",
+      ".github/workflows"
+    ])
+  ]);
+
+  const has = (name) => dependencies.has(name);
+  const hasFile = (name) => files.has(name);
+  const platforms = [];
+  if (has("expo") || has("react-native") || hasFile("eas.json")) platforms.push("expo-mobile");
+  if (has("next") || hasFile("vercel.json")) platforms.push("next-web");
+  if (has("@nestjs/core")) platforms.push("nestjs-backend");
+  if (has("express")) platforms.push("express-backend");
+  if (has("prisma") || has("@prisma/client") || hasFile("prisma/schema.prisma")) platforms.push("prisma");
+  if (has("redis") || has("ioredis")) platforms.push("redis");
+  if (hasFile("Dockerfile") || hasFile("docker-compose.yml")) platforms.push("docker");
+  if (hasFile(".github/workflows")) platforms.push("github-actions");
+  if (has("jest") || has("vitest") || hasFile("jest.config.js") || hasFile("playwright.config.ts")) platforms.push("testing");
+
+  const summary = platforms.length
+    ? platforms.join(", ")
+    : packages.length
+      ? `${packages.length} package.json file(s)`
+      : "generic repository";
+
+  return {
+    root,
+    packageFiles,
+    dependencies,
+    scripts,
+    files,
+    platforms,
+    summary
+  };
+}
+
+function selectStarterSkills(profile) {
+  const skills = [];
+  const hasPlatform = (platform) => profile.platforms.includes(platform);
+  if (hasPlatform("expo-mobile")) {
+    skills.push(skill({
+      id: "mobile-deployment",
+      name: "Mobile Deployment",
+      description: "Use for Expo, React Native, EAS build, QR/dev-client, Android/iOS preview, and mobile release tasks.",
+      prompts: ["expo", "react native", "eas", "mobile", "qr", "android", "ios", "preview", "production", "deploy"],
+      files: ["eas.json", "app.json", "app.config.ts", ".github/workflows/*"],
+      dependencies: ["expo", "react-native", "eas-cli"],
+      negatives: ["vercel", "serverless web deployment"]
+    }));
+  }
+  if (hasPlatform("next-web")) {
+    skills.push(skill({
+      id: "nextjs-web",
+      name: "Next.js Web",
+      description: "Use for Next.js routes, App Router, server/client component boundaries, Vercel deploys, and web UI tasks.",
+      prompts: ["next", "nextjs", "app router", "route", "page", "component", "vercel", "webapp"],
+      files: ["app/**", "pages/**", "next.config.*", "vercel.json"],
+      dependencies: ["next", "react"],
+      negatives: ["expo", "eas", "android", "ios"]
+    }));
+  }
+  if (hasPlatform("nestjs-backend") || hasPlatform("express-backend")) {
+    skills.push(skill({
+      id: "backend-api",
+      name: "Backend API",
+      description: "Use for backend services, API endpoints, validation, auth, controllers/routes, and service-layer changes.",
+      prompts: ["api", "backend", "service", "controller", "route", "auth", "validation", "fastify", "express", "nestjs"],
+      files: ["services/**", "src/**", "apps/**", "libs/**"],
+      dependencies: ["@nestjs/core", "express", "fastify", "zod", "class-validator"],
+      negatives: ["pure css", "static copy"]
+    }));
+  }
+  if (hasPlatform("prisma")) {
+    skills.push(skill({
+      id: "database-prisma",
+      name: "Database Prisma",
+      description: "Use for Prisma schema, migrations, query performance, repositories, and database-backed tests.",
+      prompts: ["prisma", "database", "migration", "query", "schema", "seed", "transaction"],
+      files: ["prisma/schema.prisma", "prisma/**", "src/**/repository*", "services/**/repository*"],
+      dependencies: ["prisma", "@prisma/client"],
+      negatives: ["frontend-only", "css-only"]
+    }));
+  }
+  if (hasPlatform("redis")) {
+    skills.push(skill({
+      id: "redis-cache",
+      name: "Redis Cache",
+      description: "Use for cache, queues, sessions, rate limits, Redis clients, and invalidation behavior.",
+      prompts: ["redis", "cache", "queue", "session", "rate limit", "invalidation"],
+      files: ["src/**/cache*", "services/**/cache*", "libs/**/cache*"],
+      dependencies: ["redis", "ioredis", "bullmq"],
+      negatives: ["static page"]
+    }));
+  }
+  if (hasPlatform("docker") || hasPlatform("github-actions")) {
+    skills.push(skill({
+      id: "ci-deployment",
+      name: "CI Deployment",
+      description: "Use for Docker, GitHub Actions, build logs, deploy failures, environment variables, and release pipelines.",
+      prompts: ["ci", "github actions", "docker", "deploy", "build failed", "pipeline", "environment", "secret"],
+      files: [".github/workflows/*", "Dockerfile", "docker-compose.yml", "railway.json", "render.yaml"],
+      dependencies: [],
+      negatives: ["local ui styling only"]
+    }));
+  }
+  if (hasPlatform("testing")) {
+    skills.push(skill({
+      id: "project-testing",
+      name: "Project Testing",
+      description: "Use for unit, integration, e2e, Jest, Vitest, Playwright, and focused verification tasks.",
+      prompts: ["test", "jest", "vitest", "playwright", "e2e", "coverage", "failing test"],
+      files: ["test/**", "__tests__/**", "*.spec.*", "*.test.*", "playwright.config.ts"],
+      dependencies: ["jest", "vitest", "@playwright/test"],
+      negatives: ["docs-only"]
+    }));
+  }
+  while (skills.length < STARTER_SKILL_LIMIT) {
+    const fallback = [
+      skill({
+        id: "project-implementation",
+        name: "Project Implementation",
+        description: "Use for normal feature work, bug fixes, and scoped implementation tasks in this repository.",
+        prompts: ["implement", "fix", "add", "update", "refactor", "bug"],
+        files: ["src/**", "apps/**", "services/**", "libs/**"],
+        dependencies: [],
+        negatives: ["release notes only"]
+      }),
+      skill({
+        id: "project-debugging",
+        name: "Project Debugging",
+        description: "Use for runtime errors, failed commands, logs, CI failures, and root-cause analysis.",
+        prompts: ["error", "failed", "timeout", "debug", "logs", "cannot", "fix"],
+        files: ["package.json", ".github/workflows/*", "src/**", "services/**"],
+        dependencies: [],
+        negatives: ["new feature with no failure"]
+      }),
+      skill({
+        id: "project-documentation",
+        name: "Project Documentation",
+        description: "Use for README, changelog, architecture notes, specs, and project documentation updates.",
+        prompts: ["readme", "docs", "documentation", "changelog", "spec", "guide"],
+        files: ["README.md", "docs/**", "CHANGELOG.md", "AGENTS.md"],
+        dependencies: [],
+        negatives: ["runtime bug"]
+      })
+    ].find((item) => !skills.some((existing) => existing.id === item.id));
+    if (!fallback) break;
+    skills.push(fallback);
+  }
+  return dedupeById(skills);
+}
+
+function skill({ id, name, description, prompts, files, dependencies, negatives }) {
+  return { id, name, description, prompts, files, dependencies, negatives };
+}
+
+function renderSkillMarkdown(skill) {
+  return [
+    `# ${skill.name}`,
+    "",
+    skill.description,
+    "",
+    "Use this skill when the prompt and project evidence match the metadata in `skill.yaml`.",
+    "",
+    "Before editing:",
+    "",
+    "1. Read the relevant project rules.",
+    "2. Inspect the suggested files and nearby tests.",
+    "3. Keep the change scoped to the task.",
+    "4. Run the focused verification command before final response.",
+    ""
+  ].join("\n");
+}
+
+function renderSkillYaml(skill) {
+  return [
+    `id: ${skill.id}`,
+    `name: ${skill.name}`,
+    `description: ${skill.description}`,
+    "positive_triggers:",
+    "  prompts:",
+    ...skill.prompts.map((item) => `    - ${quoteYaml(item)}`),
+    "  files:",
+    ...skill.files.map((item) => `    - ${quoteYaml(item)}`),
+    "  dependencies:",
+    ...(skill.dependencies.length ? skill.dependencies.map((item) => `    - ${quoteYaml(item)}`) : ["    - package.json"]),
+    "evidence:",
+    "  files:",
+    ...skill.files.slice(0, 4).map((item) => `    - ${quoteYaml(item)}`),
+    "  dependencies:",
+    ...(skill.dependencies.length ? skill.dependencies.map((item) => `    - ${quoteYaml(item)}`) : ["    - package.json"]),
+    "negative_triggers:",
+    "  prompts:",
+    ...skill.negatives.map((item) => `    - ${quoteYaml(item)}`),
+    "workflow:",
+    "  - Inspect repo evidence before choosing an implementation path.",
+    "  - Read the suggested files and nearest tests.",
+    "  - Implement the smallest scoped change.",
+    "  - Run focused verification and summarize evidence.",
+    ""
+  ].join("\n");
+}
+
+function renderPrimaryWorkflow(profile, skills) {
+  return [
+    "# Primary Workflow",
+    "",
+    `Use this workflow for common tasks in this repository. Detected project context: ${profile.summary}.`,
+    "",
+    "planner -> tester -> code-reviewer -> docs-manager",
+    "",
+    "1. Read the task and relevant AGENTS.md rules.",
+    "2. Check ContextOS suggested files and skills.",
+    "3. Inspect project config before choosing a deployment/framework path.",
+    "4. Implement the smallest scoped change.",
+    "5. Run focused tests or the closest available verification.",
+    "6. Summarize files changed, verification, and any remaining risk.",
+    "",
+    "Starter skills:",
+    ...skills.map((skill) => `- ${skill.id}: ${skill.description}`),
+    ""
+  ].join("\n");
+}
+
+function writeFile({ filePath, content, force, created, skipped }) {
+  if (fs.existsSync(filePath) && !force) {
+    skipped.push(filePath);
+    return;
+  }
+  fs.writeFileSync(filePath, content, "utf8");
+  created.push(filePath);
+}
+
+function findPackageJsonFiles(root) {
+  const files = [];
+  walk(root, files, (filePath) => path.basename(filePath) === "package.json", 0);
+  return files.slice(0, 20);
+}
+
+function findExisting(root, relativePaths) {
+  return relativePaths.filter((relativePath) => fs.existsSync(path.join(root, relativePath)));
+}
+
+function walk(directory, files, predicate, depth) {
+  if (depth > 4) return;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".ctx") continue;
+    const filePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) walk(filePath, files, predicate, depth + 1);
+    else if (entry.isFile() && predicate(filePath)) files.push(filePath);
+  }
+}
+
+function safeJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function findProjectRoot(cwd) {
+  let current = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(cwd);
+    current = parent;
+  }
+}
+
+function dedupeById(skills) {
+  const seen = new Set();
+  const result = [];
+  for (const skill of skills) {
+    if (seen.has(skill.id)) continue;
+    seen.add(skill.id);
+    result.push(skill);
+  }
+  return result;
+}
+
+function quoteYaml(value) {
+  return JSON.stringify(String(value));
+}

package/plugins/ctx/lib/setup-wizard.js

@@ -19,7 +19,8 @@ export function parseSetupArgs(args = []) {
     yes,
     quiet: args.includes("--quiet"),
     syncRules: !args.includes("--no-rules"),
-    syncSkills: !args.includes("--no-skills")
+    syncSkills: !args.includes("--no-skills"),
+    generateProjectContext: args.includes("--generate-project-context")
   };
 }
 
@@ -42,6 +43,7 @@ export function setupSummaryLines({
   agents = DEFAULT_AGENTS,
   syncRules = true,
   syncSkills = true,
+  generateProjectContext = false,
   promptSections = null,
   promptLimits = null
 } = {}) {
@@ -50,7 +52,8 @@ export function setupSummaryLines({
     `Agents: ${agents.join(", ") || "(none)"}`,
     `Prompt context injection: always enabled`,
     `Ruler rule/MCP sync: ${syncRules ? "enabled" : "skipped"}`,
-    `skillshare skill sync: ${syncSkills ? "enabled" : "skipped"}`
+    `skillshare skill sync: ${syncSkills ? "enabled" : "skipped"}`,
+    `Project context generation: ${generateProjectContext ? "enabled" : "skipped"}`
   ];
   if (promptSections !== null) lines.push(`Prompt sections shown: ${promptSections}`);
   if (promptLimits !== null) lines.push(`Prompt suggest limits: ${promptLimits}`);

package/plugins/ctx/lib/skill-discoverer.js

@@ -20,6 +20,10 @@ const DEFAULT_ROUTER_THRESHOLD = 0.35;
 
 const scanCache = new Map();
 
+export function clearSkillScanCache() {
+  scanCache.clear();
+}
+
 export function skillSearchRoots({ cwd = process.cwd(), home = os.homedir() } = {}) {
   return [
     path.join(cwd, ".codex", "skills"),