Make Goal Capsules discoverable as Edgebase-native commands

Add the branded /edgebase-goal surface across Claude Code, Codex, MCP prompts, setup diagnostics, and docs while preserving /goal as a compatibility alias. Also add an installed-version CLI check and make Codex setup skip user-owned unmarked skills instead of aborting.

Constraint: Public OSS setup needs pasteable agent onboarding, clear branded commands, and config preservation without committing project-local agent files.

Rejected: Keep only /goal as the explicit command | too generic for discovery and harder to associate with Edgebase after setup.

Confidence: high

Scope-risk: moderate

Directive: Keep /goal compatibility unless a future major release intentionally migrates existing users.

Tested: python3 -m compileall -q src tests; python3 -m unittest -v; git diff --check; static script scan for assets/docs; temporary venv install, setup, doctor, slash-skill file checks, hook preflight smoke, and edgebase --version.

Not-tested: Interactive slash-command rendering inside live Claude Code or Codex after client restart.

Co-authored-by: OmX <omx@oh-my-codex.dev>

Author: ychampion

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.1.6 - 2026-05-26
+
+### Added
+
+- Branded `/edgebase-goal <goal>` project skills for Claude Code and Codex, plus an `edgebase-goal` MCP prompt for clients that expose prompt menus.
+- Doctor checks and setup coverage for the new branded Goal Capsule command.
+- `edgebase --version` for quick installed-version checks.
+
+### Changed
+
+- `/goal <goal>` remains installed as a compatibility alias, while docs now lead with `/edgebase-goal` to make the command easier to associate with Edgebase.
+- Codex setup now skips unmarked existing project skills instead of aborting setup, matching the existing Claude Code preservation behavior.
+
 ## 0.1.5 - 2026-05-26
 
 ### Added

README.md

@@ -28,8 +28,8 @@ Its flagship feature is **Goal Capsules**: short, executable briefs that tell Co
 - Runs locally with no Docker, cloud service, graph database, or API key.
 - Preserves provenance for every edge: path, line, extractor, confidence, commit, and freshness.
 
-```bash
-python3 -m edgebase goal "Add passwordless login support without breaking existing OAuth"
+```text
+/edgebase-goal "Add passwordless login support without breaking existing OAuth"
 ```
 
 ```text
@@ -65,7 +65,7 @@ Patch contract:
 The final PR must include changed files, rationale, tests run, regression evidence, and unresolved assumptions.
 ```
 
-Goal Capsules are backed by the local graph index, git state, inferred tests, provenance, and working-tree freshness. They are recorded automatically by supported hooks, exposed as `/goal ...` when a manual command is useful, and called through CLI/MCP before write tools run. The same agent-facing paths also refresh optional local graph artifacts at `.edgebase/graphs/latest.html`, `.json`, and `.dot`; agents surface the paths without dumping raw graph data into context.
+Goal Capsules are backed by the local graph index, git state, inferred tests, provenance, and working-tree freshness. They are recorded automatically by supported hooks, exposed as `/edgebase-goal ...` when a manual command is useful, and called through CLI/MCP before write tools run. `/goal ...` remains installed as a shorter compatibility alias. The same agent-facing paths also refresh optional local graph artifacts at `.edgebase/graphs/latest.html`, `.json`, and `.dot`; agents surface the paths without dumping raw graph data into context.
 
 Edgebase also keeps `AGENTS.md` small, indexes the repository into a rebuildable SQLite graph, and exposes MCP tools that agents can use before editing:
 
@@ -130,7 +130,7 @@ Rules:
 - Do not add generated architecture summaries to AGENTS.md.
 - Do not remove existing agent config.
 - Do not commit unless I explicitly ask.
-- Explain that Edgebase is on by default after setup, can be disabled with `python3 -m edgebase disable --scope both`, and can be bypassed for one emergency session with `EDGEBASE_PREFLIGHT=off`.
+- Explain that Edgebase is on by default after setup, can be disabled with `edgebase disable --scope both`, and can be bypassed for one emergency session with `EDGEBASE_PREFLIGHT=off`.
 ```
 
 If you are setting up a remote repository, change the target line:
@@ -151,7 +151,7 @@ python3 -m edgebase setup --scope both
 python3 -m edgebase doctor --scope both
 ```
 
-Edgebase is enabled by default after setup. Turn it off with `python3 -m edgebase disable --scope both`.
+Edgebase is enabled by default after setup. Turn it off with `edgebase disable --scope both`.
 
 To bypass only the edit gate for one emergency session without removing MCP config:
 
@@ -168,8 +168,8 @@ EDGEBASE_PREFLIGHT=off
 | Edgebase cache/artifacts | `.edgebase/index.sqlite3`, `.edgebase/graphs/latest.*` | none | Rebuildable local graph cache plus optional visual artifacts, ignored by git |
 | Git ignore | `.git/info/exclude` | none | Locally ignores `.edgebase/` without changing committed ignore files |
 | Agent instructions | `AGENTS.md` marker block | none | Tells agents to use Edgebase automatically for broad exploration/editing |
-| Claude Code | `.mcp.json`, `.claude/settings.json`, `.claude/skills/edgebase/SKILL.md`, `.claude/skills/goal/SKILL.md` | none by default | MCP server, automatic Goal Capsules, PreToolUse stale-capsule blocking, SessionStart/PostToolUse/PreCompact/SessionEnd hooks, `/edgebase` and `/goal` skills |
-| Codex | `.codex/config.toml`, `.codex/hooks.json`, `.agents/skills/edgebase/SKILL.md`, `.agents/skills/goal/SKILL.md` | `~/.codex/config.toml` | MCP server entry, project hook config, project skills, AGENTS.md routing |
+| Claude Code | `.mcp.json`, `.claude/settings.json`, `.claude/skills/edgebase/SKILL.md`, `.claude/skills/edgebase-goal/SKILL.md`, `.claude/skills/goal/SKILL.md` | none by default | MCP server, automatic Goal Capsules, PreToolUse stale-capsule blocking, SessionStart/PostToolUse/PreCompact/SessionEnd hooks, `/edgebase`, `/edgebase-goal`, and `/goal` skills |
+| Codex | `.codex/config.toml`, `.codex/hooks.json`, `.agents/skills/edgebase/SKILL.md`, `.agents/skills/edgebase-goal/SKILL.md`, `.agents/skills/goal/SKILL.md` | `~/.codex/config.toml` | MCP server entry, project hook config, project skills, AGENTS.md routing |
 | Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` | MCP server entry |
 | Gemini CLI | `.gemini/settings.json` | `~/.gemini/settings.json` | MCP server entry |
 | OpenCode | `.opencode.json` | `~/.opencode.json` | Enabled local MCP server |
@@ -184,24 +184,31 @@ Setup uses the Python interpreter that ran setup, with `-m edgebase`, instead of
 
 Most users do not run Edgebase manually after setup.
 
-- Claude Code: `UserPromptSubmit` records and injects a Goal Capsule before planning. `PreToolUse` blocks Write/Edit/MultiEdit if no fresh capsule exists. `PostToolUse` refreshes the graph after edits. `PreCompact` saves a checkpoint, and `SessionEnd` saves a Patch Passport. Project skills `/edgebase <task>` and `/goal <goal>` are installed as explicit commands.
-- Codex: setup writes MCP config, project `.codex/hooks.json`, `[features] hooks = true`, `.agents/skills/edgebase`, `.agents/skills/goal`, and the `AGENTS.md` marker. Codex uses MCP plus project skills by default; when trusted hook support is active, the same preflight gate records capsules, blocks stale edits, refreshes after edits, checkpoints before compaction, and saves a Patch Passport on stop.
+- Claude Code: `UserPromptSubmit` records and injects a Goal Capsule before planning. `PreToolUse` blocks Write/Edit/MultiEdit if no fresh capsule exists. `PostToolUse` refreshes the graph after edits. `PreCompact` saves a checkpoint, and `SessionEnd` saves a Patch Passport. Project skills `/edgebase <task>` and `/edgebase-goal <goal>` are installed as explicit commands; `/goal <goal>` remains as a compatibility alias.
+- Codex: setup writes MCP config, project `.codex/hooks.json`, `[features] hooks = true`, `.agents/skills/edgebase`, `.agents/skills/edgebase-goal`, `.agents/skills/goal`, and the `AGENTS.md` marker. Codex uses MCP plus project skills by default; when trusted hook support is active, the same preflight gate records capsules, blocks stale edits, refreshes after edits, checkpoints before compaction, and saves a Patch Passport on stop.
 - Cursor, Gemini CLI, OpenCode, and Windsurf: Edgebase installs MCP config and a marker-bounded `AGENTS.md` instruction telling agents to use `edgebase_context` or `edgebase_goal` automatically before broad code exploration or edits. Those MCP calls update `.edgebase/graphs/latest.*` and return the artifact paths.
-- Any client: the MCP prompts named `edgebase` and `goal` are available for clients that expose MCP prompts or slash-command-style prompt menus.
+- Any client: the MCP prompts named `edgebase`, `edgebase-goal`, and `goal` are available for clients that expose MCP prompts or slash-command-style prompt menus.
 
-Useful manual commands:
+Useful explicit slash commands inside supported agent REPLs/apps:
+
+```text
+/edgebase "change the auth login flow"
+/edgebase-goal "add passwordless login without breaking OAuth"
+```
+
+Shell fallback and verification commands:
 
 ```bash
-python3 -m edgebase context "change the auth login flow" --budget 1200
-python3 -m edgebase goal "add passwordless login without breaking OAuth" --budget 1200
-python3 -m edgebase passport "add passwordless login without breaking OAuth" --test "python3 -m unittest -v: pass"
-python3 -m edgebase preflight status
-python3 -m edgebase checkpoint "handoff after auth refactor"
-python3 -m edgebase resume
-python3 -m edgebase index --changed
-python3 -m edgebase stats
-python3 -m edgebase doctor --scope both
-python3 -m edgebase disable --scope both
+edgebase context "change the auth login flow" --budget 1200
+edgebase goal "add passwordless login without breaking OAuth" --budget 1200
+edgebase passport "add passwordless login without breaking OAuth" --test "python3 -m unittest -v: pass"
+edgebase preflight status
+edgebase checkpoint "handoff after auth refactor"
+edgebase resume
+edgebase index --changed
+edgebase stats
+edgebase doctor --scope both
+edgebase disable --scope both
 ```
 
 ## What It Indexes
@@ -219,7 +226,7 @@ Dynamic-language call graphs are confidence-scored. Low-confidence call edges ar
 
 | Agent | Status | Notes |
 | --- | --- | --- |
-| Claude Code | Supported | Project `.mcp.json`; automatic UserPromptSubmit Goal Capsule; PreToolUse stale-capsule block; async PostToolUse refresh; PreCompact checkpoint; SessionEnd Patch Passport; `/edgebase` and `/goal` project skills |
+| Claude Code | Supported | Project `.mcp.json`; automatic UserPromptSubmit Goal Capsule; PreToolUse stale-capsule block; async PostToolUse refresh; PreCompact checkpoint; SessionEnd Patch Passport; `/edgebase`, `/edgebase-goal`, and `/goal` project skills |
 | Codex | Supported | Project `.codex/config.toml`, `.codex/hooks.json`, `.agents/skills`; global `~/.codex/config.toml` MCP entry for CLI discovery; verify with `codex mcp list` and `edgebase doctor` |
 | Cursor | Supported | Project and global `mcp.json`; Cursor says Composer Agent automatically uses relevant MCP tools |
 | Gemini CLI | Supported | Project and global `settings.json` with `mcpServers` |
@@ -257,7 +264,7 @@ Automation layers:
 This is not a separate graph UI or a new agent control surface; visualization is kept as a local artifact attached to the existing agent context flow.
 
 See [Architecture](docs/ARCHITECTURE.md) and [Validation](docs/VALIDATION.md).
-The latest release audit is documented in [Release Audit](docs/RELEASE_AUDIT_0.1.5.md).
+The latest release audit is documented in [Release Audit](docs/RELEASE_AUDIT_0.1.6.md).
 
 ## Benchmarks
 

docs/AGENT_CLIENTS.md

@@ -39,12 +39,19 @@ Rules:
 - Do not add generated architecture summaries to AGENTS.md.
 - Do not remove existing agent config.
 - Do not commit unless I explicitly ask.
-- Explain that Edgebase is on by default after setup, can be disabled with `python3 -m edgebase disable --scope both`, and can be bypassed for one emergency session with `EDGEBASE_PREFLIGHT=off`.
+- Explain that Edgebase is on by default after setup, can be disabled with `edgebase disable --scope both`, and can be bypassed for one emergency session with `EDGEBASE_PREFLIGHT=off`.
 ```
 
 For a remote repository, replace the target line with `Repository target: https://github.com/OWNER/REPO`.
 
-Default state after setup: **on** for selected agents. The manual fallback commands are:
+Default state after setup: **on** for selected agents. In Claude Code, Codex, and clients that expose MCP prompts as slash commands, use:
+
+```text
+/edgebase "implement password reset"
+/edgebase-goal "implement password reset without regressing login"
+```
+
+The shell fallback commands are:
 
 ```bash
 python3 -m pip install --user --upgrade git+https://github.com/ychampion/edgebase.git
@@ -55,7 +62,7 @@ python3 -m edgebase doctor --scope both
 Turn it off with:
 
 ```bash
-python3 -m edgebase disable --scope both
+edgebase disable --scope both
 ```
 
 See [Universal Agent Install Prompt](UNIVERSAL_AGENT_PROMPT.md) for a standalone copy/paste prompt.
@@ -71,11 +78,13 @@ Setup writes or updates only local configuration files:
 - `.mcp.json`: Claude Code project MCP server.
 - `.claude/settings.json`: Claude Code SessionStart, UserPromptSubmit, PreToolUse, async PostToolUse, PreCompact, and SessionEnd hooks.
 - `.claude/skills/edgebase/SKILL.md`: Claude Code project skill exposed as `/edgebase <task>`.
-- `.claude/skills/goal/SKILL.md`: Claude Code project skill exposed as `/goal <goal>`.
+- `.claude/skills/edgebase-goal/SKILL.md`: Claude Code project skill exposed as `/edgebase-goal <goal>`.
+- `.claude/skills/goal/SKILL.md`: Claude Code compatibility skill exposed as `/goal <goal>`.
 - `.codex/config.toml` and/or `~/.codex/config.toml`: Codex MCP server plus project `[features] hooks = true`.
 - `.codex/hooks.json`: Codex project hook commands for the preflight gate.
 - `.agents/skills/edgebase/SKILL.md`: Codex project skill exposed as `/edgebase <task>` where project skills are enabled.
-- `.agents/skills/goal/SKILL.md`: Codex project skill exposed as `/goal <goal>`.
+- `.agents/skills/edgebase-goal/SKILL.md`: Codex project skill exposed as `/edgebase-goal <goal>` where project skills are enabled.
+- `.agents/skills/goal/SKILL.md`: Codex compatibility skill exposed as `/goal <goal>`.
 - `.cursor/mcp.json` and/or `~/.cursor/mcp.json`: Cursor MCP server.
 - `.gemini/settings.json` and/or `~/.gemini/settings.json`: Gemini CLI MCP server.
 - `.opencode.json` and/or `~/.opencode.json`: OpenCode local MCP server.
@@ -109,14 +118,15 @@ It also writes `.claude/settings.json` hooks:
 - `PreCompact`: saves `.edgebase/checkpoints/latest.md` before compaction.
 - `SessionEnd`: saves `.edgebase/passports/latest.md` and `.json` at session end.
 
-It also writes a project skill:
+It also writes project skills:
 
 ```text
 /edgebase <task>
+/edgebase-goal <goal>
 /goal <goal>
 ```
 
-Use `/edgebase` when you want a compact read set. Use `/goal` when you want an executable Goal Capsule with blast radius, protected areas, required checks, and a patch contract. Normal coding prompts do not need the phrase "Use edgebase_context"; the prompt hook records and supplies the Goal Capsule automatically when the prompt looks like implementation, debugging, review, or investigation work.
+Use `/edgebase` when you want a compact read set. Use `/edgebase-goal` when you want an executable Goal Capsule with blast radius, protected areas, required checks, and a patch contract. `/goal` is kept as a shorter compatibility alias. Normal coding prompts do not need the phrase "Use edgebase_context"; the prompt hook records and supplies the Goal Capsule automatically when the prompt looks like implementation, debugging, review, or investigation work.
 
 Hook and MCP responses may include `.edgebase/graphs/latest.*` paths. Treat them as local visual aids for relationship inspection; do not paste raw graph JSON or DOT back into agent context.
 
@@ -162,6 +172,7 @@ And project skills:
 
 ```text
 /edgebase <task>
+/edgebase-goal <goal>
 /goal <goal>
 ```
 
@@ -170,7 +181,7 @@ Useful check:
 ```bash
 codex mcp list
 codex mcp get edgebase
-python3 -m edgebase doctor --agents codex --scope project
+edgebase doctor --agents codex --scope project
 ```
 
 The currently verified Codex CLI path reads `~/.codex/config.toml`, so the frictionless install command uses `--scope both`. Edgebase also writes `.codex/config.toml`, `.codex/hooks.json`, and `.agents/skills/*` for project-local workflows. When Codex trusts project hooks, the hook path gives the same preflight behavior as Claude Code: Goal Capsule before planning, edit block if stale, refresh after edit, checkpoint before compaction, and Patch Passport on stop.
@@ -239,35 +250,35 @@ Project scope is skipped for Windsurf because Windsurf's documented config path
 When MCP is unavailable:
 
 ```bash
-python3 -m edgebase context "implement password reset" --changed-file src/auth.py --budget 1200
-python3 -m edgebase goal "implement password reset without regressing login" --changed-file src/auth.py --budget 1200
-python3 -m edgebase passport "implement password reset without regressing login" --test "python3 -m unittest -v: pass"
-python3 -m edgebase preflight status
-python3 -m edgebase preflight refresh "implement password reset without regressing login"
-python3 -m edgebase checkpoint "handoff after password reset"
-python3 -m edgebase resume
+edgebase context "implement password reset" --changed-file src/auth.py --budget 1200
+edgebase goal "implement password reset without regressing login" --changed-file src/auth.py --budget 1200
+edgebase passport "implement password reset without regressing login" --test "python3 -m unittest -v: pass"
+edgebase preflight status
+edgebase preflight refresh "implement password reset without regressing login"
+edgebase checkpoint "handoff after password reset"
+edgebase resume
 ```
 
-MCP clients that expose prompts can also use the MCP prompts named `edgebase` and `goal`, which return the same source-backed capsule surfaces in prompt form.
+MCP clients that expose prompts can also use the MCP prompts named `edgebase`, `edgebase-goal`, and `goal`, which return the same source-backed capsule surfaces in prompt form.
 
 MCP and hook paths refresh `.edgebase/graphs/latest.html`, `.json`, and `.dot` automatically. Open or inspect those local artifacts only when a visual file relationship view helps the task.
 
 Refresh:
 
 ```bash
-python3 -m edgebase index --changed
+edgebase index --changed
 ```
 
 Disable:
 
 ```bash
-python3 -m edgebase disable --scope both
+edgebase disable --scope both
 ```
 
 Re-enable:
 
 ```bash
-python3 -m edgebase setup --scope both
+edgebase setup --scope both
 ```
 
 ## Compatibility References

docs/ARCHITECTURE.md

@@ -132,11 +132,11 @@ Claude Code has documented prompt and tool hooks, so Edgebase provides:
 - `PreCompact`: context checkpoint before compaction.
 - `SessionEnd`: Patch Passport at session end.
 - project skill `/edgebase <task>` for explicit manual refresh.
-- project skill `/goal <goal>` for explicit Goal Capsules.
+- project skill `/edgebase-goal <goal>` for explicit Goal Capsules, with `/goal <goal>` as a compatibility alias.
 
-Codex setup is MCP plus project-scoped hooks and skills. Edgebase writes `.codex/config.toml`, `[features] hooks = true`, `.codex/hooks.json`, `.agents/skills/edgebase`, and `.agents/skills/goal`. When project hooks are trusted, Codex receives the same preflight gate: prompt-time capsule, stale edit block, post-edit refresh, pre-compact checkpoint, and stop-time Patch Passport.
+Codex setup is MCP plus project-scoped hooks and skills. Edgebase writes `.codex/config.toml`, `[features] hooks = true`, `.codex/hooks.json`, `.agents/skills/edgebase`, `.agents/skills/edgebase-goal`, and `.agents/skills/goal`. When project hooks are trusted, Codex receives the same preflight gate: prompt-time capsule, stale edit block, post-edit refresh, pre-compact checkpoint, and stop-time Patch Passport.
 
-Cursor, Gemini CLI, OpenCode, and Windsurf are MCP-first. For those clients, setup writes MCP config and an `AGENTS.md` marker that instructs the agent to route broad structural context through Edgebase automatically. Edgebase also exposes MCP prompts named `edgebase` and `goal` for clients that surface prompt menus.
+Cursor, Gemini CLI, OpenCode, and Windsurf are MCP-first. For those clients, setup writes MCP config and an `AGENTS.md` marker that instructs the agent to route broad structural context through Edgebase automatically. Edgebase also exposes MCP prompts named `edgebase`, `edgebase-goal`, and `goal` for clients that surface prompt menus.
 
 MCP tool and prompt responses also refresh graph artifacts and return the local artifact paths when rendering succeeds. Rendering failures are non-fatal; Edgebase must still return the context or Goal Capsule.