@arkhera30/cli 0.8.0 → 0.8.2

package/guides/core-concepts 2.md

@@ -0,0 +1,111 @@
+---
+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

@@ -0,0 +1,127 @@
+---
+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

@@ -0,0 +1,125 @@
+---
+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

@@ -0,0 +1,108 @@
+---
+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

package/guides/getting-started 2.md

@@ -0,0 +1,94 @@
+---
+title: Getting Started with Horus
+description: Install the Horus CLI, run first setup, and connect Claude — typically under ten minutes.
+slug: getting-started
+tags: [onboarding, cli, install, setup]
+schema_version: 1
+keywords: [start, begin, first, time, first-time, install, setup, set, up, connect, configure, fresh, new, quickstart, onboarding, initialize]
+related_commands: [horus setup, horus status, horus connect, horus doctor]
+sidebar_position: 1
+---
+
+# Getting Started with Horus
+
+Horus is a local-first AI development environment. It runs Anvil (notes), Vault (knowledge), and Forge (workspaces) as containers on your machine, and connects Claude to them so your sessions have durable memory and structured workflows.
+
+This guide takes you from "nothing installed" to "asking Claude questions about your data" in about ten minutes.
+
+## Prerequisites
+
+- **Docker 24+** or **Podman 4+** with the Compose plugin
+- **Node.js 18+** (for installing the CLI via `npm`)
+- **Claude Desktop**, **Claude Code**, or **Cursor** installed
+- **Git repositories to store your data.** You'll need URLs for:
+  - One repository for Anvil notes (e.g. `horus-notes`)
+  - One repository per Vault knowledge base (e.g. `my-vault`)
+  - One repository for the Forge registry (e.g. `forge-registry`)
+
+Empty repos are fine — Horus clones them on first boot. Use HTTPS URLs, not SSH, because containers don't have your SSH keys. A GitHub token is required for private repositories.
+
+## 1. Install the CLI
+
+```bash
+npm install -g @arkhera30/cli
+horus --version
+```
+
+The CLI is published to npm as `@arkhera30/cli` and installs a single binary named `horus`.
+
+## 2. Run setup
+
+```bash
+horus setup
+```
+
+The setup wizard walks you through everything. Expect prompts for:
+
+- **Container runtime** — Docker or Podman, whichever is installed
+- **Data directory** — where Horus stores notes, knowledge, and workspaces. Default: `~/Horus/data`
+- **Host repos path** — the directory containing your local Git repositories. Forge indexes this read-only so you can ask Claude about your codebases
+- **Repository URLs** — your Anvil notes repo, one or more Vault knowledge repos, and the Forge registry
+- **GitHub tokens** — one per Git server hostname (only needed for private repos)
+
+Setup then:
+
+1. Writes config to `~/Horus/config.yaml` and `~/Horus/.env`
+2. Installs a generated `~/Horus/docker-compose.yml`
+3. Clones your repositories into the data directory
+4. Pulls container images and starts the stack
+5. Waits for every service to report healthy
+6. Automatically runs `horus connect` for any detected AI clients
+
+When setup finishes you'll see a summary with service URLs and your configured vault instances.
+
+## 3. Verify the stack is healthy
+
+```bash
+horus status
+```
+
+You should see every service reporting `healthy`, with the Anvil, Vault Router, Vault MCP, Forge, Neo4j, Typesense, and Horus UI containers running. If any service is unhealthy, run `horus doctor` for diagnostics.
+
+## 4. Open the Horus UI (optional)
+
+Horus ships with a web UI at **`http://localhost:8400`** that you can use to browse notes, knowledge pages, and workspaces without going through Claude. Useful for a quick visual check that things are working.
+
+## 5. Ask Claude something
+
+Restart Claude Desktop, Claude Code, or Cursor so it picks up the new MCP servers that `horus connect` configured. Then try these prompts:
+
+- **Anvil** — `"What's pending?"` — Claude routes this to Anvil, which searches your notes for open tasks.
+- **Anvil** — `"Create a project called My App"` — Anvil creates a typed project note.
+- **Vault** — `"How does the auth module work?"` — Claude routes to Vault's semantic search over your knowledge base.
+- **Forge** — `"List my workspaces"` — Forge returns workspace records (empty on first run — that's expected).
+
+Your Anvil and Vault repositories are empty on first install, so queries return nothing until you start creating notes and writing knowledge pages. That is normal and expected for a fresh install.
+
+## What to read next
+
+- **`horus guide core-concepts`** — the mental model for Anvil, Vault, Forge, and the supporting services
+- **`horus guide first-workspace`** — how to set up an isolated context for working on a project
+- **`horus guide first-session`** — how to start an isolated code session tied to a work item
+- **`horus guide first-note`** — how Anvil's dynamic type system works and how to create your first note
+
+If anything goes wrong during setup, `horus doctor` runs a full diagnostic and tells you exactly what to fix.