@arkhera30/cli 0.8.5 → 0.8.6

package/dist/index.js

@@ -2580,6 +2580,92 @@ async function syncSkills(runtime) {
     }
   }
 }
+var GLOBAL_SKILLS = ["horus-anvil", "horus-vault", "horus-forge", "horus-context", "capture", "triage"];
+async function fetchLatestSkillBody(controlPlaneUrl, id) {
+  const base = controlPlaneUrl.replace(/\/+$/, "");
+  const versionsRes = await fetch(`${base}/api/v1/forge/artifacts/skill/${id}/versions`);
+  if (!versionsRes.ok) return null;
+  const versionsJson = await versionsRes.json();
+  const versions = versionsJson.versions ?? [];
+  if (versions.length === 0) return null;
+  const latest = versions.slice().sort((a, b) => {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+      const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+      if (diff !== 0) return diff;
+    }
+    return 0;
+  }).pop();
+  const artifactRes = await fetch(`${base}/api/v1/forge/artifacts/skill/${id}/${latest}`);
+  if (!artifactRes.ok) return null;
+  const artifact = await artifactRes.json();
+  const b64 = artifact.files?.["SKILL.md"];
+  if (!b64) return null;
+  return Buffer.from(b64, "base64").toString("utf-8");
+}
+async function syncSkillsFromRegistry(controlPlaneUrl) {
+  const home = homedir3();
+  const skillsBase = join2(home, ".claude", "skills");
+  let synced = 0;
+  const failed = [];
+  for (const id of GLOBAL_SKILLS) {
+    try {
+      const body = await fetchLatestSkillBody(controlPlaneUrl, id);
+      if (!body) {
+        failed.push(id);
+        continue;
+      }
+      const destDir = join2(skillsBase, id);
+      mkdirSync2(destDir, { recursive: true });
+      writeFileSync3(join2(destDir, "SKILL.md"), body, "utf-8");
+      synced++;
+    } catch {
+      failed.push(id);
+    }
+  }
+  if (failed.length === 0) {
+    console.log(chalk.green(`\u2714 Synced ${synced} global skills from the control plane`));
+  } else {
+    console.log(chalk.yellow(`\u2714 Synced ${synced} global skills from the control plane`) + chalk.dim(` (failed: ${failed.join(", ")})`));
+  }
+}
+async function syncSkillsForCursorFromRegistry(controlPlaneUrl) {
+  const home = homedir3();
+  const rulesDir = join2(home, ".cursor", "rules");
+  const skillsBase = join2(home, ".cursor", "skills-cursor");
+  mkdirSync2(rulesDir, { recursive: true });
+  let synced = 0;
+  const failed = [];
+  for (const id of GLOBAL_SKILLS) {
+    try {
+      const body = await fetchLatestSkillBody(controlPlaneUrl, id);
+      if (!body) {
+        failed.push(id);
+        continue;
+      }
+      const ruleDest = join2(rulesDir, `${id}.mdc`);
+      const frontmatter = `---
+description: Horus ${id} reference
+alwaysApply: true
+---
+
+`;
+      writeFileSync3(ruleDest, frontmatter + body, "utf-8");
+      const skillDir = join2(skillsBase, id);
+      mkdirSync2(skillDir, { recursive: true });
+      writeFileSync3(join2(skillDir, "SKILL.md"), body, "utf-8");
+      synced++;
+    } catch {
+      failed.push(id);
+    }
+  }
+  if (failed.length === 0) {
+    console.log(chalk.green(`\u2714 Synced ${synced} global skills for Cursor from the control plane`));
+  } else {
+    console.log(chalk.yellow(`\u2714 Synced ${synced} global skills for Cursor from the control plane`) + chalk.dim(` (failed: ${failed.join(", ")})`));
+  }
+}
 async function syncSkillsForCursor(runtime) {
   const home = homedir3();
   const rulesDir = join2(home, ".cursor", "rules");
@@ -2692,8 +2778,14 @@ async function runConnect(config, runtime, targets, host = "localhost") {
   }
   if (targets.includes("claude-code")) {
     if (connectedMode) {
-      console.warn(chalk.yellow("[connect] Skipping skills sync \u2014 connected mode has no local forge container."));
-      console.log(chalk.dim("         TODO: fetch skills via the control plane when the skills API is available."));
+      const skillsSpinner = ora("Syncing horus-core skills from the control plane...").start();
+      try {
+        await syncSkillsFromRegistry(config.control_plane_url);
+        skillsSpinner.succeed("horus-core skills synced to ~/.claude/skills/");
+      } catch (error) {
+        skillsSpinner.warn("Could not sync skills from the control plane");
+        console.log(chalk.dim(error.message));
+      }
     } else {
       const skillsSpinner = ora("Syncing horus-core skills...").start();
       try {
@@ -2707,7 +2799,14 @@ async function runConnect(config, runtime, targets, host = "localhost") {
   }
   if (targets.includes("cursor")) {
     if (connectedMode) {
-      console.warn(chalk.yellow("[connect] Skipping Cursor rules sync \u2014 connected mode has no local forge container."));
+      const cursorRulesSpinner = ora("Syncing horus-core rules for Cursor from the control plane...").start();
+      try {
+        await syncSkillsForCursorFromRegistry(config.control_plane_url);
+        cursorRulesSpinner.succeed("horus-core rules synced to ~/.cursor/rules/ and skills to ~/.cursor/skills-cursor/");
+      } catch (error) {
+        cursorRulesSpinner.warn("Could not sync Cursor rules from the control plane");
+        console.log(chalk.dim(error.message));
+      }
     } else {
       const cursorRulesSpinner = ora("Syncing horus-core rules for Cursor...").start();
       try {

package/guides/index.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "built_at": "2026-05-31T17:23:45.012Z",
+  "built_at": "2026-06-01T09:10:29.830Z",
   "guide_count": 5,
   "guides": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkhera30/cli",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "CLI for managing the Horus AI development stack",
   "type": "module",
   "bin": {

package/guides/core-concepts 2.md

@@ -1,111 +0,0 @@
----
-title: Horus Core Concepts
-description: The mental model for Anvil, Vault, Forge, and the supporting services Horus depends on.
-slug: core-concepts
-tags: [concepts, architecture, onboarding, anvil, vault, forge]
-schema_version: 1
-keywords: [concepts, architecture, mental-model, anvil, vault, forge, neo4j, typesense, mcp, services, how-it-works, overview]
-related_commands: [horus status, horus config]
-sidebar_position: 2
----
-
-# Horus Core Concepts
-
-Horus is three primary systems (Anvil, Vault, Forge) backed by supporting services (Typesense, Neo4j, a web UI). This guide explains what each one does, why it exists as a separate service, and how they connect.
-
-## The three primary systems
-
-### Anvil — live state
-
-Anvil stores your structured, **changing** data: tasks, stories, projects, journals, notes, conversation state. Every entity is a markdown file with YAML front-matter, indexed by an embedded SQLite database for fast full-text search.
-
-Anvil has a **dynamic type system** — type definitions are YAML files, not hardcoded in the server. That means you can add new note types or extend existing ones without changing code. Claude always queries the current type schema before creating a note, so your types stay authoritative.
-
-**Use Anvil for:** tasks, projects, meeting notes, daily journals, research notes, anything you'd put in a personal knowledge-management app.
-
-**MCP endpoint:** `http://localhost:8100`
-
-### Vault — durable knowledge
-
-Vault stores your **long-lived**, structured documentation: repo profiles, architecture decisions, how-to guides, procedures, and learnings. Unlike Anvil (which tracks changing state), Vault is the place for knowledge you want to reference across sessions, weeks, and projects.
-
-Vault is a FastAPI knowledge service backed by a git repository per vault. You can run **multiple vaults** (e.g. `personal`, `work`, `client-acme`) — each is a separate repo with its own access controls and git history. A separate `vault-router` service fans out read queries to all vaults and routes writes to the correct one by UUID.
-
-Search is powered by both Typesense (full-text, typo-tolerant) and Neo4j (graph traversal for "what's related to what"). You get semantic-ish retrieval without a GPU or an external API.
-
-**Use Vault for:** how does this codebase work, what conventions does that team follow, what's the decision history for this architecture choice.
-
-**MCP endpoint:** `http://localhost:8300` (via the `vault-mcp` adapter)
-
-### Forge — execution environment
-
-Forge is the **workspace and session manager**. It does three distinct things:
-
-1. **Workspaces** — isolated contexts (MCP configs, skills, permissions) for a particular line of work. A workspace doesn't clone any code; it's just the agent environment.
-2. **Sessions** — git worktrees tied to a work item, created on demand via `forge_develop`. A session is where code changes actually happen.
-3. **Repo index** — a scanned index of your local Git repositories, made available to Claude so it can resolve and search across them.
-
-Forge also manages **plugins and skills** — reusable packages that install into the registry and add capabilities to your workspaces.
-
-**Use Forge for:** starting coded work, managing isolated contexts per project, discovering which repos exist on your machine.
-
-**MCP endpoint:** `http://localhost:8200`
-
-## Supporting services
-
-### Typesense
-
-A full-text and vector search engine that runs inside the Horus stack. Both Anvil and Vault use Typesense under the hood for fast, typo-tolerant search. You don't interact with Typesense directly — it's internal plumbing exposed only inside the Docker network.
-
-### Neo4j
-
-A graph database for relationship-aware queries. Vault uses Neo4j to store and traverse the graph of entities and edges between knowledge pages — useful for questions like "what's related to this decision" or "walk me from this ADR to the procedures that implement it". Runs on ports **7474** (browser / HTTP) and **7687** (Bolt protocol).
-
-### Horus UI
-
-A React web interface at **`http://localhost:8400`** that lets you browse Anvil notes, Vault pages, and Forge workspaces without going through Claude. It's served by an Express proxy that fans requests out to Anvil, Vault MCP, and Forge over the internal Docker network. Optional — Claude works fine without it — but handy for a visual sanity check.
-
-## How they connect
-
-Everything runs in a single Docker Compose stack on a bridge network named `horus-net`. Claude (Desktop, Code, or Cursor) connects via the Model Context Protocol (MCP) to three endpoints on your host:
-
-| Service | Host endpoint | Who talks to it |
-|---|---|---|
-| Anvil | `http://localhost:8100` | Claude, Horus UI |
-| Vault MCP | `http://localhost:8300` | Claude, Horus UI |
-| Forge | `http://localhost:8200` | Claude, Horus UI |
-
-Internally, Vault MCP proxies to the `vault-router`, which fans out to each `vault` instance on ports `8001`, `8002`, etc. Anvil and Vault both query Typesense over the internal network. Forge reads repo metadata from the host filesystem via a read-only bind mount.
-
-## Data layout
-
-All durable state lives under your data directory (default `~/Horus/data`). On a fresh install you'll see:
-
-```
-~/Horus/data/
-  notes/             Anvil notes (git repo)
-  vaults/
-    <name>/          Each vault is a separate git repo
-  registry/          Forge plugin registry (git repo)
-  workspaces/        Forge workspace directories
-  sessions/          Forge session git worktrees
-  repos/             Managed clone pool (created by forge_repo_clone)
-  config/            Forge-managed config (forge.yaml, repos.json, workspaces.json)
-  typesense-data/    Typesense index (internal)
-```
-
-User config lives at `~/Horus/config.yaml` and `~/Horus/.env`. The Docker Compose file is installed at `~/Horus/docker-compose.yml` — edit it only if you know what you're doing; `horus setup` regenerates it from the config.
-
-## Key principles
-
-1. **Everything is local.** All data stays on your machine. Search runs in-process. The only network traffic is to Anthropic (when Claude talks to the API) and to your own Git remotes for sync.
-2. **Data is durable.** Notes, knowledge, and workspaces are files on disk backed by git. Stopping the stack or removing containers never deletes your data.
-3. **Routing is automatic.** You don't pick Anvil vs Vault vs Forge — Claude reads the routing rules from the `horus-*` skills and picks the right system based on intent.
-4. **Types are dynamic.** Anvil's type system is runtime-defined. New types and fields land without a code release.
-
-## What's next
-
-- **`horus guide getting-started`** if you haven't installed yet
-- **`horus guide first-note`** to create your first Anvil entity
-- **`horus guide first-workspace`** to set up your first isolated working context
-- **`horus guide first-session`** to start your first isolated code session

package/guides/first-note 2.md

@@ -1,127 +0,0 @@
----
-title: Your First Anvil Note
-description: How Anvil's dynamic type system works and how to create your first entity — project, task, or note.
-slug: first-note
-tags: [anvil, notes, onboarding, types]
-schema_version: 1
-keywords: [note, create, anvil, type, project, task, story, journal, list-types, dynamic-types]
-related_commands: [horus status]
-sidebar_position: 5
----
-
-# Your First Anvil Note
-
-Anvil is Horus's live-state layer. It stores tasks, projects, journals, stories, meeting notes, and every other kind of structured entry you might want to track. Every entity is a markdown file with YAML front-matter, indexed by SQLite for fast search.
-
-The one thing that surprises most first-time users: **types are not hardcoded**. Anvil has a dynamic type system — you (or a plugin) define types as YAML files, and Anvil discovers them at runtime. That's why the first thing any Anvil-aware tool does is call `anvil_list_types` to ask what's currently available.
-
-## Step 1 — See what types exist
-
-Ask Claude:
-
-> "What note types exist in Anvil?"
-
-Claude will call the `anvil_list_types` tool and return a list of types with their fields, required fields, and defaults. On a fresh install you'll see core types like:
-
-- **`project`** — top-level container for related work
-- **`story`** — a feature, task, or work item (extends `task`)
-- **`task`** — a tracked to-do with status
-- **`note`** — a generic unstructured entry
-- **`journal`** — append-only chronological record for standups, session logs, decisions
-- **`meeting`** — attendees + agenda + action items
-
-Each type has:
-
-- **Required fields** (e.g. every `story` needs a `status`)
-- **Optional fields** (`priority`, `due`, `story_points`, etc.)
-- **Enum fields** with allowed values (e.g. `status: open | in-progress | blocked | done`)
-
-Don't memorize these — the tool returns them every call.
-
-## Step 2 — Create a project
-
-> "Create a project called 'My First Horus Project' with status `active`."
-
-Claude will pick the right type, populate the required fields, and call `anvil_create_entity`. Under the hood that looks like:
-
-```
-anvil_create_entity({
-  type: "project",
-  title: "My First Horus Project",
-  fields: { status: "active" },
-  body: "Brief description of what this project is for."
-})
-```
-
-The response gives you a UUID (`entityId`) and the file path where Anvil wrote the note on disk — something like `~/Horus/data/notes/my-first-horus-project.md`.
-
-## Step 3 — Add a task to the project
-
-Projects are just containers — the actual work lives as `task` or `story` entities that reference them. Ask Claude:
-
-> "Create a task in My First Horus Project called 'Try out `horus help`' with priority P2-medium."
-
-Anvil will create a new task and add the project reference via a typed edge. A lightly-edited version of the tool call:
-
-```
-anvil_create_entity({
-  type: "task",
-  title: "Try out horus help",
-  fields: {
-    project: "[[My First Horus Project]]",
-    priority: "P2-medium",
-    status: "open"
-  }
-})
-```
-
-Two things worth noting:
-
-- **References are wiki-links.** Anvil uses `[[Title]]` format for cross-entity references, not UUIDs. The ingestion pipeline resolves the link to a UUID under the hood.
-- **Edges are real.** Fields like `project` aren't just strings — they create typed edges in Anvil's graph, visible via `anvil_get_edges` and `anvil_get_related`.
-
-## Step 4 — Search for what you just created
-
-> "What's pending in My First Horus Project?"
-
-Claude calls `anvil_query_view` with a filter on project + status, or `anvil_search` with a free-text query. Both hit Anvil's SQLite index and return the matching entities. You'll see the task you just created.
-
-You can also:
-
-- **Group results as a board:** `anvil_query_view({ type: "task", project: "[[My First Horus Project]]", format: "board", groupBy: "status" })`
-- **Filter by tags:** `anvil_search({ query: "onboarding", tags: ["experimental"] })`
-- **Get a subtree** starting from a project: `anvil_get_subtree({ rootId: "..." })`
-
-## Step 5 — Update without overwriting
-
-Anvil uses **PATCH semantics** for updates. When you call `anvil_update_entity`, only the fields you pass are changed — everything else is preserved. That means you can safely update a single field without worrying about clobbering unrelated metadata.
-
-> "Mark that task as in-progress."
-
-```
-anvil_update_entity({
-  noteId: "abc-...",
-  fields: { status: "in-progress" }
-})
-```
-
-**Journals are a special case:** they're append-only. Updating a journal's body *appends* the new content instead of replacing it, which is useful for daily standups and decision logs.
-
-## Common starter flows
-
-A few things you'll probably try in your first week:
-
-- **Daily journal** — create a `journal` type each morning; Claude appends new entries throughout the day
-- **Project kanban** — one `project`, many `task`s, `anvil_query_view` with `format: "board"` gives you a live kanban
-- **Conversation state** — Claude auto-creates a `conversation-state` entity to track open questions and decisions for a session
-- **SDLC workflow** — `project` → `story` → `task` with typed edges, driven by the `sdlc-*` skills
-
-## Where the data lives
-
-All Anvil entities are plain markdown files under `<data_dir>/notes/`, tracked in git. You can browse them, edit them in your text editor, commit them, and push them to your remote — Anvil picks up file-system changes via its file watcher. Anvil also periodically pulls the remote and pushes local changes, so your data sync across machines works the same way as git.
-
-## What's next
-
-- **`horus guide first-workspace`** — set up an isolated agent context so your notes, skills, and MCP configs stay organized
-- **`horus guide first-session`** — tie a code session to a story or task you just created
-- **`horus guide core-concepts`** — how Anvil relates to Vault and Forge in the bigger picture

package/guides/first-session 2.md

@@ -1,125 +0,0 @@
----
-title: Your First Forge Code Session
-description: How to start an isolated code session on a repo for a specific work item, using forge_develop.
-slug: first-session
-tags: [forge, session, onboarding, git, worktree]
-schema_version: 1
-keywords: [session, worktree, forge-develop, code, branch, git, isolate, coding, start-work]
-related_commands: [horus status]
-sidebar_position: 4
----
-
-# Your First Forge Code Session
-
-A **Forge session** is a git worktree on disk, tied to a single work item and a single repository. When you're ready to actually write code for a task — not just plan it, not just take notes — you start a session. The session gives you an isolated, feature-branched workspace that doesn't interfere with whatever else is checked out in your main clone of the repo.
-
-Sessions are created by the **`forge_develop`** MCP tool. One call does everything: finds the repo, creates the worktree, checks out a feature branch, wires up the commit scripts, and hands you back a path to work in.
-
-## Before you start
-
-You need two things:
-
-1. **A repo registered with Forge.** Run `forge_repo_list()` to see what Forge has indexed, or `forge_repo_resolve({ name: "..." })` to look up a specific one. Forge scans the `host_repos_path` you set during `horus setup` and auto-adds repos it finds.
-2. **A work item in Anvil.** Sessions are namespaced by work item ID, so you need one before `forge_develop` will do anything. See `first-note` for how to create one.
-
-## Create your first session
-
-Ask Claude:
-
-> "Start a code session for work item `<your-work-item-id>` on repo `<your-repo>`."
-
-Or call the MCP tool directly:
-
-```
-forge_develop({
-  repo: "my-project",
-  workItem: "abc12345",
-  branch: "feature/abc12345-initial-work"
-})
-```
-
-Forge returns something like:
-
-```json
-{
-  "status": "created",
-  "sessionId": "sess-...",
-  "sessionPath": "/Users/you/Horus/data/sessions/abc12345-my-project",
-  "branch": "feature/abc12345-initial-work",
-  "baseBranch": "main",
-  "repo": "my-project",
-  "repoSource": "managed"
-}
-```
-
-The **`sessionPath`** is where you do all your work. It's a real git worktree — a separate working directory that shares the underlying git object store with your main clone of the repo. You can `cd` into it, edit files, run tests, and commit like you would in any other clone.
-
-## What's in a session directory
-
-When you open the session path, you'll see your repo checked out at the feature branch, plus one extra directory:
-
-```
-<sessionPath>/
-  <your repo contents>
-  .forge/
-    scripts/
-      commit.sh       # stage-aware conventional commit wrapper
-      push.sh         # push to the right remote for this repo's workflow
-      create-pr.sh    # create a PR against the correct target (handles fork vs owner vs contributor)
-```
-
-Always commit through `.forge/scripts/commit.sh <type> <scope> <description>`. It handles the conventional-commit formatting and picks up per-repo workflow metadata so you don't have to remember which remote to push to or what the target branch is. Same applies to `push.sh` and `create-pr.sh`.
-
-## Resume a session
-
-`forge_develop` is **idempotent** for the same work item + repo pair. If the session already exists, Forge resumes it instead of creating a new one:
-
-```json
-{
-  "status": "resumed",
-  "sessionId": "sess-...",
-  "sessionPath": "...",
-  "branch": "feature/abc12345-initial-work"
-}
-```
-
-That means you can re-invoke `forge_develop` any time you restart an agent session or switch machines — it picks up where you left off without polluting your git state.
-
-## Workflow confirmation on first use
-
-The first time you create a session for a new repo, Forge may return:
-
-```json
-{ "status": "needs_workflow_confirmation", "detected": { ... } }
-```
-
-This is Forge asking: "I see a `fork` / `owner` / `contributor` workflow here — is that right?" Re-call `forge_develop` with the `workflow` parameter set to confirm. Forge saves the choice so future sessions on the same repo don't need the confirmation again.
-
-## Clean up when the work is done
-
-Sessions hang around until the linked work item transitions to `done` or `cancelled`. Once that happens, you can bulk-clean:
-
-```
-forge_session_cleanup({ auto: true })
-```
-
-This removes every session whose work item is complete. Or you can check for stale sessions manually:
-
-```
-forge_session_list()
-```
-
-## Sessions vs. workspaces
-
-This trips up everyone the first time, so here it is one more time:
-
-- A **workspace** is an agent *environment* — MCP configs, skills, CLAUDE.md, permissions. It doesn't touch any repo.
-- A **session** is a git *worktree* — an actual checkout of a repo, tied to a work item.
-
-You can have one workspace and ten sessions inside it, each working on a different story or repo. Or you can skip workspaces and create sessions directly — they work fine on their own.
-
-## What's next
-
-- **`horus guide first-note`** — create a work item in Anvil to link your session to
-- **`horus guide first-workspace`** — set up an isolated agent context that wraps multiple sessions
-- **`horus guide core-concepts`** — the mental model behind the workspace / session / repo split

package/guides/first-workspace 2.md

@@ -1,108 +0,0 @@
----
-title: Your First Forge Workspace
-description: What a Forge workspace is, how it differs from a code session, and how to create your first one.
-slug: first-workspace
-tags: [forge, workspace, onboarding]
-schema_version: 1
-keywords: [workspace, forge, context, isolation, isolated, create, mcp, skills, plugins, environment, setup, initialize]
-related_commands: [horus status]
-sidebar_position: 3
----
-
-# Your First Forge Workspace
-
-A **Forge workspace** is an isolated agent context — a bundle of MCP configs, installed skills, environment variables, and permission settings — that Claude loads when you're working on something specific. Workspaces do **not** clone code. That's what sessions are for (see `first-session`).
-
-Think of a workspace as "the agent environment for working on project X", and a session as "the git worktree where I'm actually editing code for story Y inside project X". One workspace, many sessions.
-
-## Why workspaces exist
-
-Without workspaces, every Claude session shares the same MCP tools, skills, and environment. That's fine at first, but as you start using Horus for real work you'll notice:
-
-- Different projects want different skills loaded (one project uses `horus-anvil`, another needs a custom `client-conventions` skill)
-- Sensitive projects shouldn't share environment variables with throwaway experiments
-- You want a clean context when you switch from personal work to client work
-- MCP server configs can drift per-project (e.g. different vault instances)
-
-Workspaces solve this by giving each line of work its own agent context.
-
-## What's in a workspace
-
-When Forge creates a workspace, it writes:
-
-- **`.claude/settings.local.json`** — MCP server URLs for Anvil, Vault, and Forge, resolved to host-accessible endpoints (not Docker-internal ones)
-- **`.claude/skills/`** — a subset of skills from the Forge registry, installed for this workspace
-- **`workspace.env`** — environment variables sourced by shells and child processes inside the workspace
-- **`CLAUDE.md`** — a workspace-level instruction file that gets loaded into Claude's context on every session
-- **Permission hooks** — optional pre/post hooks that enforce policies
-
-The workspace directory lives under `<data_dir>/workspaces/<workspace-name>/` on your host and is also mounted into the Forge container so the MCP server can read and update it.
-
-## Create your first workspace
-
-Open Claude and ask it to create a workspace for you:
-
-> "Create a workspace called `draft` for general experimentation with the `sdlc-*` skills loaded."
-
-Claude will call `forge_workspace_create` under the hood. If you want to do it in a single MCP tool call directly, the arguments look like:
-
-```
-forge_workspace_create({
-  name: "draft",
-  description: "General experimentation workspace",
-  skills: ["sdlc-planner", "sdlc-developer", "sdlc-reviewer", "sdlc-story"],
-  mcp_servers: ["anvil", "vault", "forge"]
-})
-```
-
-Forge returns the workspace path (e.g. `~/Horus/data/workspaces/draft/`) and writes all the config files mentioned above.
-
-## Use the workspace
-
-To actually *work* inside a workspace, open Claude Code or Cursor in the workspace directory:
-
-```bash
-cd ~/Horus/data/workspaces/draft
-claude
-```
-
-Claude Code picks up `.claude/settings.local.json` automatically and loads the configured MCP servers and skills. The `CLAUDE.md` in the workspace root becomes your project-level instructions. From that point on, every tool call Claude makes is scoped to this workspace's configuration.
-
-## Workspaces vs. code sessions
-
-Here's the easiest way to keep them straight:
-
-| Workspace | Session |
-|---|---|
-| Agent environment (MCP, skills, permissions) | Git worktree on disk |
-| One per project or line of work | One per work item (story / task) |
-| Does NOT clone any repo | Is a git worktree checked out to a feature branch |
-| Persists until you explicitly delete it | Auto-cleans when the linked work item is done |
-| Created via `forge_workspace_create` | Created via `forge_develop` |
-
-You typically have one workspace per project and many sessions inside that workspace over time as you pick up different work items.
-
-## Listing and inspecting workspaces
-
-```
-forge_workspace_list()
-forge_workspace_status({ name: "draft" })
-```
-
-The list tool returns every workspace Forge knows about. The status tool tells you its configuration and whether any sessions are linked to it.
-
-## Cleaning up
-
-When you're done with a workspace:
-
-```
-forge_workspace_delete({ name: "draft" })
-```
-
-This removes the workspace directory and deregisters it from Forge. If the workspace has active sessions, you'll need to clean those up first (see `first-session`).
-
-## What's next
-
-- **`horus guide first-session`** — create a git worktree tied to a work item so you can actually edit code
-- **`horus guide first-note`** — create the work item in Anvil that a session links to
-- **`horus guide core-concepts`** — the mental model for why workspace, session, and repo are three separate concepts