# https://github.com/JasonCoate/xurgo-atlas Project Manual

Generated at: 2026-06-21 00:26:56 UTC

## Table of Contents

- [Overview and Quick Start](#page-1)
- [Daemon, CLI, and MCP Integration](#page-2)
- [Managed Documentation Lifecycle](#page-3)
- [Storage, Root Safety, and Release Workflow](#page-4)

<a id='page-1'></a>

## Overview and Quick Start

### Related Pages

Related topics: [Daemon, CLI, and MCP Integration](#page-2), [Managed Documentation Lifecycle](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/README.md)
- [AGENTS.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/AGENTS.md)
- [package.json](https://github.com/JasonCoate/xurgo-atlas/blob/main/package.json)
- [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CONTRIBUTING.md)
- [src/core/templates.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/templates.ts)
- [src/core/project.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/project.ts)
- [src/core/risk.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/risk.ts)
- [src/core/markdown.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/markdown.ts)
- [src/mcp/tools.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/mcp/tools.ts)
</details>

# Overview and Quick Start

## Purpose and Scope

Xurgo Atlas is a **standalone, local-first documentation and project-context service** for AI-assisted development. It provides MCP-capable AI clients a governed way to read project docs, search context, and propose documentation changes with an audit trail. Atlas complements a repository — it does not replace Git, the source tree, the issue tracker, or the AI client itself. Source: [README.md:1-7]().

The project is published on npm as `xurgo-atlas` (version `0.2.1`) with a Node.js requirement of `>=22` and is licensed under MIT. Source: [package.json:1-50](). The CLI binary is exposed as `xurgo-atlas`, mapping to `./dist/index.js`, and a stable version string is emitted via both `-v` and `--version` for consumer-friendly checks. Source: [CHANGELOG.md:1-20]().

## Core Capabilities at a Glance

Atlas exposes its functionality through MCP tools (defined in `src/mcp/tools.ts`) and CLI commands. The most important capabilities are:

| Capability | Type | Purpose |
|---|---|---|
| `docs.list` / `docs.read` / `docs.read_section` | MCP read | Enumerate and read tracked Markdown files, with bounded `maxChars`/`offset` reads |
| `docs.propose_patch` / `docs.preview_diff` / `docs.commit_patch` | MCP write | Propose, preview, and apply unified-diff patches with re-validation |
| `docs.create_branch` | MCP write | Spin up an agent branch from any source branch |
| `docs.history` / `docs.restore_file` | MCP read | Inspect and roll back to prior revisions |
| `docs.capabilities` | MCP read | Read-only capability summary for MCP clients |
| `atlas.project_identity` | MCP read | Project/root binding, Git identity, and root-safety visibility |
| `docs.preview_export` | MCP read | Read-only preview of an export before applying it |

Source: [src/mcp/tools.ts:1-200](). The risk engine that gates commits lives in `src/core/risk.ts` and flags protected files, large deletions, heading removal, and full-file replacements. Source: [src/core/risk.ts:1-50]().

## Installation and Initialization

### Install

Atlas supports three install modes, all documented in the README:

```bash
# Global install for the normal CLI workflow
npm install -g xurgo-atlas

# Try without installing
npx xurgo-atlas ...

# Project-local automation
npm install -D xurgo-atlas
```

Source: [README.md:13-25]().

### Initialize a Project

`xurgo-atlas init` creates or preserves a `.xurgo-atlas/project.json` marker for the project folder, then writes starter docs and a safety policy. After init, normal commands can run from the project root or a nested subdirectory without repeating `--project-id` or `--project-root`. Source: [README.md:21-25]().

```bash
xurgo-atlas --version
xurgo-atlas --help
xurgo-atlas init --project-id my-project
```

Optional templates seed curated Markdown files for common archetypes (`saas`, `cli-tool`, etc.). Templates are purely additive — they never overwrite existing content. Source: [src/core/templates.ts:1-100]().

```bash
xurgo-atlas init --templates
xurgo-atlas init --template mcp-server --project-id my-project
```

### Lifecycle Flow

```mermaid
flowchart LR
  A[Install xurgo-atlas] --> B[init --project-id]
  B --> C{Start daemon?}
  C -- yes --> D[daemon start]
  D --> E[mcp-config --json]
  E --> F[MCP client connects]
  C -- no --> G[stdio MCP server]
  G --> F
  B --> H[Agent uses docs.* tools]
  F --> H
```

Source: [README.md:13-30]().

## Start the Daemon and Connect MCP Clients

After initialization, start the local daemon and print the JSON config that MCP clients consume:

```bash
xurgo-atlas daemon start
xurgo-atlas mcp-config --json
```

Source: [README.md:19-22]().

The daemon defaults to port `3737` and can be reconfigured with `--port` and `--host`. A community issue (#3) clarified that **passing `--port` explicitly is the recommended escape hatch** when the default is already in use or when release verification runs alongside an existing daemon. Source: [community context, issue #3]().

A second community issue (#1) reported fresh-install runs failing with "port already occupied" because an earlier daemon (e.g. PID 94632 on `127.0.0.1:3737`) was still alive. The safe pattern is to either stop the previous daemon (`xurgo-atlas daemon stop`) or invoke a different port explicitly. Source: [community context, issue #1]().

## Safety, Validation, and the Audit Trail

Atlas enforces a strict safety contract for AI agents operating against it. The rules in `AGENTS.md` require:

- **Never directly overwrite documentation files** — all changes flow through MCP.
- **Read before you write** — `docs.read` returns a `baseRevision` that must be echoed back via `docs.propose_patch`.
- **Propose, then commit** — `docs.propose_patch` validates the patch, then `docs.commit_patch` re-validates the base revision before applying.
- **Respect risk assessments** — high-risk patches require `riskOverride: "accept"`.
- **Classify managed-doc export drift** before commit: required, valid sync, or stale drift to revert.

Source: [AGENTS.md:1-30]().

Tracked files (`STATUS.md`, `AGENTS.md`, `.docs-policy.yml`, `docs/manifest.yml`, etc.) are protected from direct edits and are catalogued in a generated `manifest.yml` that pairs each entry with a `role`, `priority`, and `summary`. Source: [src/core/project.ts:1-150](). Markdown section reads use an ATX-heading walker that ignores headings inside fenced code blocks, enabling token-efficient targeted reads. Source: [src/core/markdown.ts:1-50]().

## Validation and Releases

The npm scripts in `package.json` support layered validation:

| Script | Command | Use |
|---|---|---|
| `validate:quick` | `npm run test:fast && npm run build` | Fast pre-commit loop |
| `validate:full` | `npm run build && npm test && npm pack --dry-run` | Full pre-release gate |
| `verify:installed` | `node scripts/happy-path-smoke.mjs` | Smoke-test the installed CLI |

Source: [package.json:30-60]().

A release-verification step documented in community issue #2 calls for **explicit post-merge managed-store reconciliation**: after Git merges that touch Atlas-managed docs, verify managed `main` matches source `main` and that `docs.manifest` is still valid before signing off a release. Source: [community context, issue #2]().

## See Also

- [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CHANGELOG.md) — full release history (v0.1.0 → v0.2.0)
- [CONTRIBUTING.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CONTRIBUTING.md) — contribution and release-process rules
- [SECURITY.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/SECURITY.md) — private security reporting channel
- `atlas.project_identity` MCP tool — project/root binding and root-safety visibility (added in v0.2.0)

---

<a id='page-2'></a>

## Daemon, CLI, and MCP Integration

### Related Pages

Related topics: [Overview and Quick Start](#page-1), [Managed Documentation Lifecycle](#page-3), [Storage, Root Safety, and Release Workflow](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/README.md)
- [package.json](https://github.com/JasonCoate/xurgo-atlas/blob/main/package.json)
- [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CHANGELOG.md)
- [AGENTS.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/AGENTS.md)
- [src/core/templates.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/templates.ts)
- [src/core/project.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/project.ts)
- [src/cli/mcp-config.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/cli/mcp-config.ts)
- [src/mcp/tools.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/mcp/tools.ts)
- [CONTRIBUTING.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CONTRIBUTING.md)
</details>

# Daemon, CLI, and MCP Integration

## Overview

Xurgo Atlas is a local-first documentation and project-context service that gives developers and MCP-capable AI clients a governed way to read project docs, find context, and propose changes with an audit trail [Source: [README.md:3-5]()]. The integration of the **CLI**, the **daemon**, and the **MCP HTTP endpoint** forms the core delivery surface of the package: the CLI wraps lifecycle commands, the daemon hosts the long-running process, and the MCP endpoint exposes tools and resources to AI clients.

The package ships a single binary named `xurgo-atlas` (mapped to `./dist/index.js` in `package.json`) and is published under the keywords `xurgo-atlas`, `mcp`, `model-context-protocol`, and `documentation` [Source: [package.json:1-25]()]. It targets Node.js 22 or later, which is required because the runtime uses built-in `node:sqlite` for its event log and proposal storage [Source: [CHANGELOG.md:60-65]()].

## CLI Surface and Daemon Lifecycle

### Quick start sequence

The recommended entry path is short and explicit. After a global install, the user runs the version flag, initializes a project, starts the daemon, and prints an MCP configuration blob:

```bash
xurgo-atlas --version
xurgo-atlas --help
xurgo-atlas init --project-id my-project
xurgo-atlas daemon start
xurgo-atlas mcp-config --json
```

Source: [README.md:14-22]()

`init` is purely additive: it creates a local `.xurgo-atlas/project.json` marker for the project folder, seeds starter docs through curated templates, and never overwrites existing content [Source: [src/core/project.ts:1-60](), [src/core/templates.ts:1-30]()]. Optional init templates (`--templates` or `--template mcp-server`) further enrich the starting set, but they are documentation templates, not application scaffolds [Source: [README.md:30-38]()]. Once initialized, normal commands can run from the project root or any nested subdirectory without re-passing `--project-id` or `--project-root`.

### Daemon commands and default port

The daemon is invoked with `xurgo-atlas daemon start` and exposes its MCP endpoint at `http://127.0.0.1:3737/mcp` by default [Source: [src/cli/mcp-config.ts:80-105]()]. The CLI also supports `xurgo-atlas mcp-config --json`, which prints a JSON blob containing the resolved endpoint, the project binding (`cwd`, `projectId`, `projectRoot`, `projectSource`, `registeredProjectRoot`), Git identity, and a `mcpServers` block ready to drop into a client configuration [Source: [src/cli/mcp-config.ts:30-78]()].

| CLI surface | Purpose | Default / Required value |
|-------------|---------|--------------------------|
| `xurgo-atlas -v`, `--version` | Stable version check for consumer CLIs | Stable string |
| `xurgo-atlas init` | Create project marker + starter docs | `--project-id` optional |
| `xurgo-atlas daemon start` | Start the local daemon | Host `127.0.0.1`, port `3737` |
| `xurgo-atlas mcp-config --json` | Print JSON MCP client config | Endpoint and project binding |
| `xurgo-atlas list / history / export` | Enriched CLI output for tracked docs | Project-resolved |

Source: [README.md:14-22](), [src/cli/mcp-config.ts:80-105](), [CHANGELOG.md:6-12]()

### Port conflicts and the `--port` escape hatch

Community issue **#1** observed that during fresh-install verification the default port `3737` was already occupied by an existing Xurgo Atlas daemon for the same checkout (PID 94632), and that the running command included an explicit `xurgo-atlas dist/index.js daemon --host 127.0.0.1 --port 3737`. No conflicting process was killed automatically. The recommended escape is to pass `--port` explicitly when the default is unavailable — for example `--port 4737` was used in the 0.1.1 release verification path [Source: community context, issues #1 and #3].

This means the daemon lifecycle is intentionally conservative: it does not silently terminate a peer daemon on the same checkout, and it does not pick a free port automatically. Operators must decide whether to stop the previous daemon, choose a different `--port`, or run the new daemon on a different host binding.

## MCP Server and Tool Surface

### Server architecture

The MCP server is created per request inside the daemon. The tool registration block in `src/mcp/tools.ts` enumerates a stable, versioned set of tools whose names and input schemas are exposed via `tools/list`. Each tool is wired through a Zod schema and a handler, and per-request project resolution injects the resolved `projectId` into the call arguments so daemon callers do not have to repeat it [Source: [src/mcp/tools.ts:60-140]()].

```mermaid
flowchart LR
    Client[MCP-capable AI client] -->|HTTP POST /mcp| Daemon[Xurgo Atlas daemon]
    Daemon -->|resolveProjectForRequest| Project[(.xurgo-atlas/project.json + Git)]
    Daemon -->|tools/list| Registry[Tool & resource registry]
    Daemon -->|tools/call| Handlers[Zod-validated handlers]
    Handlers -->|read/write/search/propose/commit| Store[(Git-backed doc store + SQLite event log)]
    Handlers -->|read-only identity| Identity[atlas.project_identity]
    Handlers -->|preview export| Preview[docs.preview_export]
```

### Read, search, and identity tools

Read-side tools are bounded and token-efficient. `docs.read` supports `maxChars` and `offset` for chunked retrieval, and `docs.read_section` returns a single Markdown section by ATX heading while ignoring headings inside fenced code blocks [Source: [src/mcp/tools.ts:80-120]()]. `docs.search` performs content search, and `docs.capabilities` returns a read-only summary of managed-docs scope, available context tools, guarded-write support, and retrieval/search status [Source: [src/mcp/tools.ts:130-145]()].

`atlas.project_identity` is a read-only runtime identity and root-safety snapshot. It reports the active project/root binding, marker and Git identity, authoritative write safety, descriptive root-ledger and recovery warnings, and a recommended next step. It is explicitly **not** a replacement for `xurgo-atlas mcp-config --json` [Source: [src/mcp/tools.ts:145-155]()]. Both surfaces — `atlas.project_identity` and `mcp-config --json` — are intended to let clients confirm they are operating on the intended project folder before running guarded write or export operations [Source: [README.md:42-48]()].

### Guarded-write and proposal lifecycle

The guarded-write path is implemented as a multi-step workflow:

1. `docs.create_branch` — create an agent branch from a source branch.
2. `docs.propose_patch` — store a unified-diff proposal (with `baseRevision`, `intent`, `summary`, `patch`); the patch must use standard `---/+++` headers and `@@` hunks, and `*** Begin Patch`-style apply blocks are rejected.
3. `docs.preview_diff` — preview the stored diff, risk level, and approval requirements without committing.
4. `docs.commit_patch` — re-validate the base revision and apply the patch; high-risk patches require `riskOverride: "accept"`.
5. `docs.list_proposals` / `docs.discard_proposal` — manage the proposal queue; the default filter surfaces pending proposals so stale internal drafts can be discovered.

Source: [src/mcp/tools.ts:30-75](), [CHANGELOG.md:30-50]()

`docs.propose_document` extends this lifecycle to brand-new files under approved managed paths (such as `docs/atlas/**` or `docs/spec/**`) and to repair manifest-listed documents that are missing on disk [Source: [src/mcp/tools.ts:20-35]()]. Safety policy is configurable in `.docs-policy.yml`, which is generated alongside `AGENTS.md` and `STATUS.md` during init and treated as a highest-priority `safety-policy` entry in the manifest [Source: [src/core/project.ts:60-120](), [src/core/templates.ts:30-90]()].

## Configuration, Project Identity, and Release Validation

### Project binding and root safety

`mcp-config --json` emits a structured object with `projectId`, `projectRoot`, `projectSource`, `requestedCwd`, `registeredProjectRoot`, a `git` block (with `worktreeRoot`), a `safety` block, and a `rootLedger` block [Source: [src/cli/mcp-config.ts:30-78]()]. The companion `atlas.project_identity` MCP tool surfaces the same information in a compact read-only form, including descriptive root-ledger and recovery warnings and a recommended next step [Source: [src/mcp/tools.ts:145-155]()]. The `startCommand` block in the MCP config tells clients how to bring the daemon up if it is not already running: `{ command: "xurgo-atlas", args: ["daemon", "start"] }` [Source: [src/cli/mcp-config.ts:60-72]()].

### Managed-store reconciliation after merges

Community issue **#2** highlighted that during the 0.1.1 release, managed-store reconciliation became an important release-validation step after Git merges involving Atlas-managed docs. The release workflow must explicitly verify that the managed `main` branch matches the source `main` branch after merges, and that `docs.manifest` remains valid. The AGENTS.md safety rules reinforce this: agents must classify managed-doc export drift before commit and report whether changes are required for the branch, valid managed-store/source synchronization, or unrelated stale drift to revert [Source: [AGENTS.md:30-45](), community context issue #2].

### Test and validation tiers

The repository ships three test tiers in `package.json` [Source: [package.json:30-55]()):

- `npm run test:fast` — runs a focused subset covering package bin alias, MCP metadata, search, CLI usage, registry, storage migration, and private RC artifact.
- `npm run test:integration` — runs project, daemon, daemon-lifecycle, and HTTP-server suites.
- `npm run validate:full` — builds, runs the full test suite, and dry-runs `npm pack` with a clean cache.
- `npm run verify:installed` — runs `scripts/happy-path-smoke.mjs` to validate an installed package end-to-end.

### Version output and consumer checks

The 0.2.0 release stabilized `xurgo-atlas -v` and `xurgo-atlas --version` so that consumer CLIs and CI scripts can rely on a clean version string. The same release added `docs.preview_export`, a read-only preview of the export boundary that complements `docs.export` [Source: [CHANGELOG.md:1-15](), [README.md:42-48]()]. Together with `atlas.project_identity`, these read-only surfaces give consumers a way to inspect project binding, root safety, and export behavior before issuing guarded writes.

## Common Failure Modes and Operator Notes

- **Port already in use** (issue #1): the daemon does not auto-kill a peer process. Stop the previous daemon or pass `--port` explicitly (for example `--port 4737`).
- **Explicit `--port` in release verification** (issue #3): when the release verification script targets a non-default port, document the value and reason in the release notes so that smoke tests do not race the default-port daemon.
- **Stale proposal pile-up**: `docs.list_proposals` defaults to pending proposals; agents and operators should drain or discard stale internal drafts rather than letting them linger.
- **Export drift after merge** (issue #2): before release signoff, reconcile managed `main` with source `main` and confirm `docs.manifest` is valid.
- **Node toolchain drift**: when the active shell is not on the expected Node 22 toolchain, AGENTS.md recommends `nvm use --silent 22` before running npm validation or packaging commands [Source: [AGENTS.md:15-25]()].

## See Also

- [Setup](docs/atlas/setup.md) — install options, first run, initialization, templates, and contributor setup.
- [Root / Worktree Safety Model](docs/atlas/root-worktree-safety.md) — project identity, worktree safety, and export boundaries.
- [Development Workflow](docs/atlas/development-workflow.md) — validation tiers, smoke tests, and local package checks.
- [Release Checklist](docs/atlas/release-checklist.md) — release gates and ongoing release maintenance workflow, including managed-store reconciliation.

---

<a id='page-3'></a>

## Managed Documentation Lifecycle

### Related Pages

Related topics: [Daemon, CLI, and MCP Integration](#page-2), [Storage, Root Safety, and Release Workflow](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [AGENTS.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/AGENTS.md)
- [README.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/README.md)
- [CHANGELOG.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CONTRIBUTING.md)
- [package.json](https://github.com/JasonCoate/xurgo-atlas/blob/main/package.json)
- [src/mcp/tools.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/mcp/tools.ts)
- [src/core/risk.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/risk.ts)
- [src/core/templates.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/templates.ts)
- [src/core/project.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/project.ts)
</details>

# Managed Documentation Lifecycle

## Overview

Xurgo Atlas treats a curated set of Markdown files as a **managed documentation store**. Instead of letting AI agents edit files directly, Atlas routes every change through MCP tools (`docs.propose_patch`, `docs.preview_diff`, `docs.commit_patch`, `docs.propose_document`, `docs.export`, `docs.restore_file`) backed by a Git store and a SQLite event log. The lifecycle spans initialization, proposal, validation, commit, and reconciliation with the source tree.

The lifecycle is governed by `AGENTS.md`, which states: *"Never directly overwrite documentation files. All documentation changes must go through the Xurgo Atlas MCP server."* Source: [AGENTS.md:1-2](). Atlas complements the repository — it does not replace Git, the source tree, the issue tracker, or the AI client. Source: [README.md:5-7]().

## Initialization

`xurgo-atlas init` seeds a project with the managed-doc skeleton. It writes a `.xurgo-atlas/project.json` marker, a `docs/` directory, a `docs/manifest.yml`, an `AGENTS.md`, a `STATUS.md`, and an `implementation-checklist.md`. Existing files are preserved — Atlas is purely additive. Source: [src/core/project.ts]() and [README.md:23-25]().

Optional templates seed archetype-specific starter docs:

| Template | Extra Files | Source |
|----------|-------------|--------|
| `default` | `docs/project-brief.md` | [src/core/templates.ts]() |
| `saas` | `docs/product-brief.md`, `docs/development-workflow.md` | [src/core/templates.ts]() |
| `cli-tool` | `docs/cli-surface.md`, `docs/development-workflow.md` | [src/core/templates.ts]() |
| `mcp-server` | `docs/mcp-surface.md`, `docs/development-worklist.md` | [src/core/templates.ts]() |

After init, normal commands run from the project root or any nested subdirectory without repeating `--project-id` or `--project-root`. Source: [README.md:25-27]().

## Proposal Lifecycle

The managed lifecycle follows a strict multi-step flow: read → propose → preview → commit. Each step is exposed as an MCP tool with a Zod-validated input schema.

```mermaid
flowchart LR
    A[docs.read] --> B[docs.propose_patch / docs.propose_document]
    B --> C[docs.preview_diff]
    C --> D{Risk OK?}
    D -- No --> E[docs.discard_proposal]
    D -- Yes --> F[docs.commit_patch]
    F --> G[Git store + SQLite event log]
    G --> H[docs.export]
```

- `docs.read` returns content with a stable `revision` hash that must be passed back as `baseRevision` on every propose. Source: [src/mcp/tools.ts]().
- `docs.propose_patch` requires a unified diff with `---/+++` headers and `@@` hunks; `apply_patch`-style blocks (`*** Begin Patch`) are rejected. Source: [src/mcp/tools.ts]().
- `docs.propose_document` can also repair a manifest-listed document that is missing on disk. Source: [src/mcp/tools.ts]().
- `docs.commit_patch` re-validates `baseRevision` and requires `riskOverride: "accept"` for high-risk patches. Source: [src/mcp/tools.ts]().
- Stale proposals auto-transition to a `stale` lifecycle status; `docs.list_proposals` defaults to `pending` so drafts don't linger. Source: [src/mcp/tools.ts]().

Agent rules require reading before writing, never deleting content silently, and creating branches (`docs.create_branch`) for multi-step edits. Source: [AGENTS.md:11-18]().

## Risk & Safety

Atlas runs every patch through `assessPatchRisk` before commit. A patch is marked **high-risk** if any of the following triggers fire. Source: [src/core/risk.ts]():

| Trigger | Why It Is High-Risk |
|---------|--------------------|
| Deletes more than 25% of the file | Possible destructive edit |
| Removes Markdown headings | Breaks `docs.read_section` and navigation |
| Replaces the entire file | Hides intent of change |
| Modifies `AGENTS.md` or `.docs-policy.yml` | Changes agent contract or policy |
| Path is policy-protected (`policy.isPathProtected`) | Path flagged in `.docs-policy.yml` |
| Patch-only deletion (no other content) | Likely silent overwrite attempt |

Additional safety rules enforced by the agent contract: forbidden operations include silent delete, whole-file replace without `baseRevision`, and overwrite without diff. `AGENTS.md` and `.docs-policy.yml` modifications require the `intent` or `summary` to reference safety/agent rule keywords. Source: [CHANGELOG.md]().

## Reconciliation, Export & Release

The managed store must stay consistent with the source tree after every merge. Community issue **#2 ("Document post-merge managed-store reconciliation")** highlights that after any Git merge involving Atlas-managed docs, release validation must verify that the managed `main` matches the source `main` before signoff, and `docs.manifest` must remain valid. Source: [CHANGELOG.md]() and [AGENTS.md:27-29]().

`docs.export` writes a managed branch back to the working tree. `docs.preview_export` (added in v0.2.0) lets agents preview the export before it touches disk, reducing accidental drift. Source: [CHANGELOG.md]().

Before committing an export, agents must **classify managed-doc drift** into one of three buckets, per AGENTS rule #8:

1. **Required for this branch** — keep and commit.
2. **Valid managed-store/source synchronization** — keep and commit.
3. **Unrelated stale drift** — revert before commit.

Source: [AGENTS.md:27-29](). Drift is never kept just because export produced it.

## Common Failure Modes

| Symptom | Likely Cause | Mitigation |
|---------|--------------|------------|
| `commit_patch` rejected with "stale baseRevision" | A concurrent change updated the file | Re-run `docs.read`, re-propose, re-commit |
| High-risk warning on `AGENTS.md` edit | Intent/summary missing safety keyword | Add safety/agent keyword to `intent` or `summary` and pass `riskOverride: "accept"` |
| `docs.export` produces unexpected file changes | Source tree has drifted from managed store | Classify each diff per AGENTS rule #8 before commit |
| Fresh install reports port 3737 already in use | Another Xurgo Atlas daemon is already bound to that checkout | Community issue #1 — improve daemon port-conflict UX; use `lsof -i :3737` to inspect |
| Release verification port mismatch | CI runs with `--port 4737` but default docs reference 3737 | Community issue #3 — pass `--port` explicitly when deviating from default |

Sources: [README.md:13-21](), [AGENTS.md:27-29](), [CHANGELOG.md](), and the community discussion summaries for issues #1–#3.

## See Also

- [Daemon & Port Configuration](#) — default port 3737, `--port` flag, lifecycle commands.
- [Proposal Storage & Risk Assessment](#) — SQLite-backed `doc_proposals` table and `assessPatchRisk` policy engine.
- [Templates & Project Archetypes](#) — `default`, `saas`, `cli-tool`, `mcp-server` starter docs.
- [AGENTS.md Safety Contract](#) — agent-facing rules for read-before-write, drift classification, and protected files.

---

<a id='page-4'></a>

## Storage, Root Safety, and Release Workflow

### Related Pages

Related topics: [Overview and Quick Start](#page-1), [Daemon, CLI, and MCP Integration](#page-2), [Managed Documentation Lifecycle](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [docs/atlas/storage-migration.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/docs/atlas/storage-migration.md)
- [docs/atlas/root-worktree-safety.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/docs/atlas/root-worktree-safety.md)
- [docs/atlas/project-resolution-hardening.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/docs/atlas/project-resolution-hardening.md)
- [docs/atlas/sqlite-root-safety-ledger.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/docs/atlas/sqlite-root-safety-ledger.md)
- [docs/atlas/release-checklist.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/docs/atlas/release-checklist.md)
- [src/core/storage.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/storage.ts)
- [src/core/root-ledger.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/core/root-ledger.ts)
- [src/mcp/tools.ts](https://github.com/JasonCoate/xurgo-atlas/blob/main/src/mcp/tools.ts)
- [AGENTS.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/AGENTS.md)
- [STATUS.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/STATUS.md)
- [README.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/JasonCoate/xurgo-atlas/blob/main/CONTRIBUTING.md)
</details>

# Storage, Root Safety, and Release Workflow

## Overview

Xurgo Atlas is a local-first documentation and project-context service for AI-assisted development. The three concerns covered on this page — storage migration, root safety, and release workflow — form the operational backbone that keeps Atlas trustworthy when used from multiple working directories, worktrees, or release branches.

Atlas never replaces Git, the source tree, or the user's AI client. Instead, it layers a governed documentation store, a SQLite-backed root-safety ledger, and a hardened release-validation process on top of an existing project [Source: [README.md:1-12]()]. The storage and root-safety subsystems are designed to fail safely when the host environment is ambiguous (for example, when the daemon is started from a different worktree than the one used to initialize the project) [Source: [src/core/root-ledger.ts:1-80]()].

## Storage Architecture

Atlas uses a Git-backed documentation store combined with a SQLite event log. The SQLite layer records every project binding and root observation in a dedicated `root_worktree_ledger` table, which is indexed by `(project_id, last_seen_at DESC)` for fast lookup of the most recent observation [Source: [src/core/root-ledger.ts:24-46]()]. The store is migrated lazily through a conservative copy-only apply path so that older deployments can adopt new storage layouts without destructive in-place rewrites [Source: [STATUS.md:1-15]()]. A merged `storage migration git metadata repair` change also fixes bare `HEAD`, workdir alternates, and origin remote URLs when stores are copied between environments [Source: [STATUS.md:1-15]()].

```mermaid
flowchart LR
    A[Project Root] -->|init| B[Git-backed Doc Store]
    A --> C[SQLite Event Log]
    B --> D[doc_proposals Table]
    B --> E[doc_history Table]
    C --> F[root_worktree_ledger Table]
    F --> G{identity_key}
    G -->|match| H[safe_for_writes=1]
    G -->|mismatch| I[refuse write]
```

Storage operations are bounded by a risk assessment that compares the proposed patch against the existing file. High-risk patches (large deletions, heading removal, whole-file replacement, or modifications to `AGENTS.md` / `.docs-policy.yml`) require explicit `riskOverride: "accept"` before commit [Source: [src/mcp/tools.ts:48-56](), [src/core/risk.ts:14-46]()].

## Root Safety System

The root safety subsystem centers on the `root_worktree_ledger` table. Each row records a stable observation of a project root and includes the Git worktree root, Git common dir, current branch, HEAD commit, and a set of safety flags:

| Column | Purpose |
|--------|---------|
| `canonical_project_root` | Resolved absolute path used for write targets |
| `git_worktree_root` / `git_common_dir` | Git environment captured at observation time |
| `git_branch` / `git_head` | Branch state captured at observation time |
| `safe_for_writes` | 1 if observation matches expected binding, 0 otherwise |
| `ambiguous` / `root_mismatch` / `marker_missing` / `marker_mismatch` | Diagnostic flags for partial-binding states |
| `registered_project_root_*` / `daemon_project_root_*` / `git_*` | Drift indicators between CLI, daemon, and Git views |
| `warnings_json` | Human-readable warnings attached to the observation |
| `first_seen_at` / `last_seen_at` / `observation_count` | Lifecycle telemetry |

Source: [src/core/root-ledger.ts:6-58]()

The ledger is queried by an aggregate summary that returns the distinct counts of canonical project roots, Git worktree roots, and Git common dirs seen for a project, plus the timestamp of the most recent observation [Source: [src/core/root-ledger.ts:60-80]()]. When the ledger cannot be opened, Atlas returns an `unavailableRootLedgerSummary` carrying the accumulated warnings instead of silently failing [Source: [src/core/root-ledger.ts:80-95]()].

The optional `atlas.project_identity` MCP tool exposes a read-only view of this ledger for clients that need project/root binding, Git identity, and root-safety visibility without taking a write lock [Source: [README.md:1-12](), [STATUS.md:1-15]()].

## Release Workflow

Atlas treats release signoff as a multi-step validation pipeline. The published release checklist (see `docs/atlas/release-checklist.md`) gates a tag on a full `npm run validate:full`, which combines `tsc`, the Vitest suite, and `npm pack --dry-run` against an isolated cache [Source: [package.json:30-45](), [CONTRIBUTING.md:15-25]()]. Validation is intentionally CI-friendly, and the maintainers explicitly request that contributors do **not** add publish-on-main automation, PR-triggered publishing, or release secrets without prior maintainer direction [Source: [CONTRIBUTING.md:17-25]()].

Three community-identified pain points shape the current workflow:

1. **Daemon port conflicts.** Fresh-install verification observed that port `3737` was already bound by a stale Atlas daemon (PID 94632) for the same checkout. The recommended escape is to pass `--port` explicitly (e.g. `--port 4737`) when the default port is occupied, and to surface the conflicting PID in daemon startup output [Source: [README.md:14-35](), [STATUS.md:1-15]()].
2. **Post-merge managed-store reconciliation.** During the 0.1.1 release, managed `main` drifted from source `main` after Git merges. The current rule requires explicitly re-syncing managed `main` to source `main` and re-validating `docs.manifest` before signoff [Source: [AGENTS.md:6-10](), [STATUS.md:1-15]()].
3. **Root-safe workflows.** Project identity resolution must be reproducible from any subdirectory, and the `safe_for_writes` flag must be `1` for any commit to proceed. The reconciliation loop inspects all managed-doc / export changes and classifies each as required, valid sync, or stale drift to revert [Source: [AGENTS.md:6-10]()].

Atlas also enforces a documentation safety contract: agents must never directly overwrite documentation files, must always read before writing, must use `docs.propose_patch` with a `baseRevision`, and must finalize changes with `docs.commit_patch` [Source: [AGENTS.md:1-10](), [src/mcp/tools.ts:18-56]()].

## See Also

- [Daemon Lifecycle and Port Handling](#) — covers the `daemon start` flow and `--port` / `--host` flags referenced in the release workflow.
- [MCP Tool Reference](#) — full schemas for `docs.propose_patch`, `docs.commit_patch`, `atlas.project_identity`, and `docs.preview_export`.
- [AGENTS.md Safety Rules](#) — the canonical agent contract that drives the reconciliation rules above.
- [Storage Migration Apply Copy](#) — design notes for the conservative copy-only migration path.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: JasonCoate/xurgo-atlas

Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/JasonCoate/xurgo-atlas/issues/1

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/JasonCoate/xurgo-atlas

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/JasonCoate/xurgo-atlas

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/JasonCoate/xurgo-atlas

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/JasonCoate/xurgo-atlas

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/JasonCoate/xurgo-atlas

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/JasonCoate/xurgo-atlas

<!-- canonical_name: JasonCoate/xurgo-atlas; human_manual_source: deepwiki_human_wiki -->