# Agent-driven installation

Use this runbook whenever the user asks you to install Cartographer — a repository link and a
conversation is the normal starting point, and it is enough. Execute every command in order; report
the expected result before continuing.

**Establish one input first: the git remote for the user's first Knowledge Base (KB).** A KB is a
git repository and its remote is what makes it durable and syncable, so the remote is required, and
on this path it is almost always the thing nobody supplied. Ask for it now — an empty repository
they own (GitHub, Gitea, or any git host) — rather than discovering at step 3 that you need a URL
you do not have. Only if the user explicitly accepts a throwaway, local-only KB do you proceed
without one.

## 1. Install Cartographer

Detect the platform:

```bash
uname -s
```

Expected output: `Darwin` on macOS or `Linux`. The installer supports those two and no others; on any
other platform, stop and report it. On macOS,
first check for Homebrew:

```bash
command -v brew
```

Expected output: the path to `brew`. If it is present, install Cartographer:

```bash
brew install beppetemp/tap/cartographer
```

Expected output: Homebrew reports that `cartographer` was installed. If `brew` is absent, install
the current release instead:

```bash
curl -fsSL https://raw.githubusercontent.com/BeppeTemp/cartographer/main/install.sh | sh
```

Expected output: the installer reports the destination of the `cartographer` binary.

Confirm the binary is available:

```bash
cartographer version
```

Expected output: a Cartographer version.

## 2. Install the local service

```bash
cartographer service install
```

Expected output: the native user service is installed and started. It listens on
`http://127.0.0.1:39273` and its data directory is ready for KBs.

## 3. Mount the first KB

When the remote already contains a KB, mount it through Cartographer:

```bash
cartographer kb clone <git-remote-url> --restart
```

Expected output: `KB "<name>" mounted at <data-dir>/<name>`, followed by service restart and
health guidance. Do not clone the repository into the service data directory yourself.

When the remote is an empty repository, create the KB in it:

```bash
cartographer kb create <name> --remote <git-remote-url> --restart
```

Expected output: `KB "<name>" created at <data-dir>/<name>`, then `origin: <git-remote-url>`,
followed by `service healthy`.

Ask for a remote before running either command. Only if the user explicitly accepts a throwaway,
local-only KB — not backed up and never synchronized — fall back to `cartographer kb create <name>
--no-remote --restart`, and state that limitation back to them.

## 4. Connect the executing agent

First identify the installed provider name:

```bash
cartographer agents
```

Expected output: a table listing `claude`, `opencode`, `codex`, `kiro`, `hermes`, and `antigravity` with installation state.
Connect the executing provider with `--agents`; for example, for Codex:

```bash
cartographer connect --agents codex
```

Expected output: the generated MCP configuration paths and a reminder to restart the agent session.
With two or more mounted KBs, Cartographer creates one MCP entry per KB the client is bound to.

**Ask which KBs this client should receive.** On a first connect against a server mounting two or
more KBs, `connect` requires the choice — it will not deliver all of them by default (D190), because
everything a KB carries (skills, subagents, hooks, instructions, MCP descriptors) is delivered with
it:

```bash
cartographer connect --agents codex --kb <name>          # repeatable, or comma-separated
cartographer connect --agents codex --kb all             # every mounted KB, recorded explicitly
```

In an interactive terminal the same choice is offered as a list after the connect form. Prefer the
narrowest selection that does the job, and verify the result with `cartographer status`: the bound
KBs are printed per provider, with `explicit` next to them.

A KB bound this way is readable from **every** directory on the machine. If the user works in two
separate perimeters with the same client, offer the alternative before the first sync, because it
is free only now (D193):

```bash
cartographer connect --agents codex --kb <name> --workspace <repository path>
```

That confines those KBs to one repository instead — their skills, subagents and hooks are
materialized into that repository's own configuration and nowhere else. `cartographer workspace
bind/unbind/list` manages it afterwards.

## 5. Verify the installation

```bash
cartographer version
curl -fsS http://127.0.0.1:39273/health
cartographer status
```

Expected output: a version, then health JSON containing `"ready":true`, then in-sync status with
exit code 0.

Confirm the instructions actually reach the model, not just the disk. `cartographer status` and
`cartographer doctor` now check the provider's own precedence chain (D189), but the provider's own
tooling is the ground truth — for Codex:

```bash
codex debug prompt-input
```

Expected output: a `cartographer:kb:*` section. If it is absent while `status` reports the
instructions installed, report it: a provider precedence rule Cartographer does not model yet.

`connect` provisioned the bundled skills, including `cartographer-ops`. Use that skill for ongoing
operations, diagnosis, upgrades, and synchronization after installation. From there the bundled
`kb-create` and `kb-import` skills take over: `kb-create/references/artifacts.md` for authoring the
KB's skills, subagents, hooks and MCP descriptors, and `kb-create/references/secrets.md` for the
SOPS encryption flow.

## 6. Tell the user to restart their agent session

This is a step you cannot perform: the session that must restart is the one you are running in.
State it to the user explicitly, as the last thing you say:

> Restart your agent session now. The MCP tools and the provisioned skills are loaded at session
> start, so until you do, Cartographer is installed but invisible to me.

Omitting this is the single most common way a correct installation is reported as broken.

## Failures

| Observed symptom | Next action |
|---|---|
| `command -v brew` has no output | Run the `install.sh` command in step 1. |
| The user's agent shows no Cartographer MCP tools after a successful `connect` | The session was not restarted. Repeat step 6 — this is not a failed install. |
| `cartographer status` exits non-zero immediately after install | The service may still be starting: wait a few seconds and retry once before diagnosing. |
| The service reports that port 39273 is busy | Stop or reconfigure the process using the port, then rerun `cartographer service install`. |
| `kb clone` reports a git authentication failure | Configure ambient credentials (an SSH agent for SSH remotes or a git credential helper for HTTPS), then rerun the same `kb clone` command. |
| `kb clone` reports a host key that is not in `known_hosts` | Connect once with `ssh <host>` to review and accept the key yourself, then rerun. The clone never accepts a host key on your behalf (D173). |
| `kb clone` times out | The forge did not answer within the budget: check the remote is reachable, then rerun with `--timeout <duration>` if the repository is simply large. |
| `kb clone`/`kb create` refuse because the client points at a remote server | These commands act on the local server's data dir. Mount the KB on the remote deployment instead, or pass `--local` (act locally anyway) or `--data <dir>` (name the target). |
| `kb clone` says `not an OKF KB` | Use the `kb-import` skill to import the remote into an OKF KB, push it, then rerun `kb clone`. |
| `kb create` says a KB needs a git remote | Ask the user for an empty repository URL and rerun with `--remote <url>`; use `--no-remote` only if they explicitly accept a local-only KB. |
| `kb create --remote` fails to push (non-fast-forward, or the remote is not empty) | The repository already has content: mount it with `cartographer kb clone <git-remote-url> --restart` instead. |
| `kb create --remote` reports a git authentication failure | Configure ambient credentials (an SSH agent for SSH remotes or a git credential helper for HTTPS), then rerun the same command. The scaffold is deliberately kept (D156): the command prints how to fix the author/push, or how to remove it. |