# https://github.com/mrt150683-lgtm/atlas-cms Project Manual

Generated at: 2026-07-15 03:59:48 UTC

## Table of Contents

- [Project Introduction and System Architecture](#page-1)
- [Memory Engine, Knowledge Graph and Data Pipeline](#page-2)
- [AI Integration, Verification and Hermes Sentinel Quality Gate](#page-3)
- [Agent Interfaces, UI Viewer and Discovery Layer](#page-4)

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

## Project Introduction and System Architecture

### Related Pages

Related topics: [Memory Engine, Knowledge Graph and Data Pipeline](#page-2), [AI Integration, Verification and Hermes Sentinel Quality Gate](#page-3), [Agent Interfaces, UI Viewer and Discovery Layer](#page-4)

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

The following source files were used to generate this page:

- [README.md](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/README.md)
- [codebase_memory_system_design_spec.md](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/codebase_memory_system_design_spec.md)
- [docs/ATLAS_OPERATIONS.md](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/docs/ATLAS_OPERATIONS.md)
- [pyproject.toml](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/pyproject.toml)
- [cms/__init__.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/__init__.py)
- [cms/config.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/config.py)
</details>

# Project Introduction and System Architecture

Atlas CMS is a Content Management System built around an explicit principle: the codebase must remain intelligible to AI coding agents over the long term. The repository pairs a runnable Python `cms/` package with a dedicated "Codebase Memory System" specification, positioning the project as both an executable application and a self-describing substrate that machine readers can navigate deterministically.

## Purpose and Scope

The project frames itself around a single guiding requirement — an AI assistant working on the CMS must be able to retrieve precise, structured information about the codebase on demand, rather than relying on brute-force file reading. The `README.md` introduces Atlas as the integrated environment in which that capability lives `Source: [README.md:1-15]()`. The accompanying design specification clarifies why a dedicated memory layer is necessary: large files, cross-file dependencies, and evolving subsystems cause naive context loading to miss critical information `Source: [codebase_memory_system_design_spec.md:1-20]()`. The scope is therefore not simply "a CMS," but rather "a CMS plus the tooling that keeps the CMS intelligible to its own maintainers and AI agents."

The operations manual in `docs/ATLAS_OPERATIONS.md` reinforces this framing by treating day-2 concerns — deployment, observability, and incident response — as first-class subsystems of the project rather than afterthoughts `Source: [docs/ATLAS_OPERATIONS.md:1-30]()`. Together, these documents establish that Atlas is intended to be authored and maintained with sustained AI assistance, and that the architecture is shaped accordingly.

## System Architecture

Atlas is composed of three cooperating layers, each represented by a distinct artifact in the repository. These layers are intentionally separated so that each can evolve on its own cadence while remaining contractually aligned with the others.

### Application Layer

The runnable CMS is implemented as a Python package named `cms`. Its entry point `cms/__init__.py` re-exports the public surface of the system so that downstream consumers, including the memory tooling, can import a stable contract `Source: [cms/__init__.py:1-15]()`. Configuration is centralized in `cms/config.py`, which declares the runtime settings and environment-driven parameters that gate application behavior `Source: [cms/config.py:1-25]()`. Concentrating configuration in one module keeps the rest of the codebase free of scattered constants and gives the memory layer a single, inspectable target to describe.

### Memory Layer

The Codebase Memory System is documented in `codebase_memory_system_design_spec.md`, which describes a structured store of project knowledge — module maps, dependency edges, behavioral notes, and operational facts — that agents query instead of re-reading source. The specification frames memory as a deterministic contract: every entry must be reproducible from the source tree, so the memory and the codebase cannot drift `Source: [codebase_memory_system_design_spec.md:21-60]()`. This layer is the differentiating feature of Atlas compared with a conventional CMS scaffold.

### Operations Layer

`docs/ATLAS_OPERATIONS.md` covers the operational surface of the project: build, deploy, monitoring, and recovery procedures `Source: [docs/ATLAS_OPERATIONS.md:30-80]()`. Because the memory layer is intended to be refreshed as code changes, operations are explicitly coupled to memory updates — a deploy is not considered complete until the corresponding memory entries have been re-validated `Source: [docs/ATLAS_OPERATIONS.md:80-120]()`.

### Component Diagram

```mermaid
flowchart TB
    subgraph Ops["Operations Layer"]
        OPS["docs/ATLAS_OPERATIONS.md"]
    end
    subgraph Memory["Memory Layer"]
        SPEC["codebase_memory_system_design_spec.md"]
    end
    subgraph App["Application Layer"]
        INIT["cms/__init__.py"]
        CONF["cms/config.py"]
        PKG["cms/* package modules"]
    end
    PKG --> INIT
    PKG --> CONF
    SPEC -. refreshes .-> PKG
    OPS -. runs/validates .-> PKG
    OPS -. re-validates .-> SPEC
```

## Module Organization and Packaging

The repository is laid out so that application code, its specification, and its operational documentation live at predictable top-level paths. The `cms/` package contains the executable code; the project root holds the specification and the README; a dedicated `docs/` directory holds operational runbooks. Dependencies, tool configuration, and packaging metadata live in `pyproject.toml`, which is the authoritative source for build, install, and test commands `Source: [pyproject.toml:1-30]()`. This separation — code, spec, ops, and packaging — is intentional: each artifact serves a different audience (runtime, AI agent, operator, and build system respectively) and each can be versioned and reviewed independently.

## Configuration, Dependencies, and Operations

`cms/config.py` is the single point at which environment-driven settings are defined and consumed, keeping the rest of the application free of scattered constants and giving operators one place to audit runtime behavior `Source: [cms/config.py:1-40]()`. `pyproject.toml` records the runtime and development dependencies, the entry points, and the project metadata required for installation and distribution `Source: [pyproject.toml:30-60]()`. The operations manual assumes this configuration module is the only sanctioned source of mutable runtime state and describes how operators should change settings without bypassing it `Source: [docs/ATLAS_OPERATIONS.md:80-130]()`. The README links these artifacts together, providing the entry narrative for new contributors and AI agents alike `Source: [README.md:1-30]()`. Together, the six referenced files form a closed loop: configuration defines behavior, packaging delivers it, the memory layer describes it, and operations keep it correct.

---

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

## Memory Engine, Knowledge Graph and Data Pipeline

### Related Pages

Related topics: [Project Introduction and System Architecture](#page-1), [AI Integration, Verification and Hermes Sentinel Quality Gate](#page-3), [Agent Interfaces, UI Viewer and Discovery Layer](#page-4)

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

The following source files were used to generate this page:

- [cms/scanner.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/scanner.py)
- [cms/graph_builder.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/graph_builder.py)
- [cms/semantic_state.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/semantic_state.py)
- [cms/summarizer.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/summarizer.py)
- [cms/features.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/features.py)
- [cms/intent.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/intent.py)
</details>

# Memory Engine, Knowledge Graph and Data Pipeline

The Memory Engine is the central reasoning layer of `atlas-cms`. It converts raw repository content into a queryable semantic structure, allowing the CMS to answer questions, summarize code, classify intent, and reuse prior context across sessions. The Knowledge Graph is the persistent substrate of this engine, while the Data Pipeline is the sequence of transformations that turns source files into graph nodes, edges, and semantic summaries.

## Purpose and Scope

The Memory Engine exists to give the CMS three capabilities that are not present in a conventional content store:

1. **Long-lived semantic context.** Pages, code snippets, and user interactions are not stored as opaque blobs. They are encoded into a representation that downstream components can reason about.
2. **Cross-document relationships.** Entities extracted from different files are linked into a single graph, enabling traversal queries such as "which features depend on this intent?" or "what summaries reference this scanner token?"
3. **Pipeline-driven ingestion.** Every new artifact entering the CMS passes through the same ordered transformations, so the graph remains consistent regardless of the input source.

The engine is bounded by the `cms/` package. It does not own storage, transport, or UI rendering; it only owns the representation layer between raw input and the CMS's higher-level agents.

Source: [cms/scanner.py:1-40](), [cms/semantic_state.py:1-30]()

## Data Pipeline

The Data Pipeline is the ordered sequence of stages that converts a raw artifact into structured memory. Each stage has a single responsibility and a well-defined input/output contract.

| Stage | File | Role | Output |
|---|---|---|---|
| Scanner | `cms/scanner.py` | Walks the repository and emits raw token / chunk streams | Tokenized chunks |
| Features | `cms/features.py` | Derives structural and semantic features from chunks | Feature vectors |
| Intent | `cms/intent.py` | Classifies the purpose of each chunk | Intent label |
| Semantic State | `cms/semantic_state.py` | Merges features and intent into a session-level state object | State snapshot |
| Graph Builder | `cms/graph_builder.py` | Persists nodes and edges into the Knowledge Graph | Graph mutations |
| Summarizer | `cms/summarizer.py` | Produces condensed text views of graph neighborhoods | Summary strings |

The Scanner is the entry point. It is responsible for deterministic traversal of the repository so that re-ingestion produces identical token streams. Features then project those tokens into a feature space that is independent of the source language. Intent adds a categorical label that biases later retrieval. Semantic State holds the running session view, so that the pipeline is incremental rather than purely stateless. Graph Builder writes the merged representation into the persistent Knowledge Graph, and the Summarizer is the read-side counterpart, generating human-readable descriptions on demand.

Source: [cms/scanner.py:20-80](), [cms/features.py:1-50](), [cms/intent.py:1-45](), [cms/semantic_state.py:30-90](), [cms/graph_builder.py:1-70](), [cms/summarizer.py:1-60]()

## Knowledge Graph Construction

The Knowledge Graph is the persistent memory of the engine. It is built and maintained by `cms/graph_builder.py`, but its shape is determined by the contracts of every upstream stage.

The graph has two primary node kinds:

- **Entity nodes**, derived from `cms/features.py`. Each node carries the feature vector and the original chunk reference.
- **Intent nodes**, derived from `cms/intent.py`. These act as categorical anchors that allow the graph to be sliced by purpose (for example, separating configuration from behavioral code).

Edges are produced by `cms/graph_builder.py` based on co-occurrence within the same `semantic_state` snapshot, explicit references detected by the scanner, and transitive links inferred from shared features. The builder is intentionally append-only within a transaction; a failed transaction leaves the graph unchanged, which keeps the memory consistent under partial failure.

`cms/semantic_state.py` mediates between the pipeline and the graph. It buffers intermediate state, resolves duplicates, and decides when a state is stable enough to be flushed as graph mutations. This separation allows the pipeline to run with low memory overhead even when ingesting large repositories.

Source: [cms/graph_builder.py:40-120](), [cms/semantic_state.py:50-110](), [cms/features.py:30-70]()

## Read Path: Retrieval and Summarization

The read path mirrors the write path in reverse. A query enters through the scanner interface, which locates candidate nodes. The semantic state is reconstructed for the candidate set, intent labels are used as filters, and `cms/summarizer.py` collapses each neighborhood into a bounded text representation.

Summarization is bounded by the same semantic state object used during ingestion. This symmetry is intentional: it guarantees that a summary describes exactly the graph region that was visible when the data was written, which prevents drift between stored memory and retrieved memory.

Source: [cms/summarizer.py:20-90](), [cms/semantic_state.py:80-130](), [cms/intent.py:30-70]()

## Architectural Diagram

```mermaid
flowchart LR
    A[Scanner] --> B[Features]
    B --> C[Intent]
    B --> D[Semantic State]
    C --> D
    D --> E[Graph Builder]
    E --> F[(Knowledge Graph)]
    F --> G[Summarizer]
    D --> G
    C --> G
```

The diagram shows that `Semantic State` is the single convergence point of the write path, while `Summarizer` is the single convergence point of the read path. Both sides depend on `Intent` as a categorical filter, which keeps the memory engine interpretable rather than purely numeric.

---

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

## AI Integration, Verification and Hermes Sentinel Quality Gate

### Related Pages

Related topics: [Project Introduction and System Architecture](#page-1), [Memory Engine, Knowledge Graph and Data Pipeline](#page-2), [Agent Interfaces, UI Viewer and Discovery Layer](#page-4)

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

The following source files were used to generate this page:

- [cms/providers.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/providers.py)
- [cms/review.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/review.py)
- [cms/suggest.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/suggest.py)
- [cms/verify.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/verify.py)
- [cms/align.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/align.py)
- [cms/chat.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/chat.py)
</details>

# AI Integration, Verification and Hermes Sentinel Quality Gate

## 1. Overview and Scope

The "AI Integration, Verification and Hermes Sentinel Quality Gate" feature in `atlas-cms` provides a structured pipeline that connects Large Language Model (LLM) providers to content authoring workflows. The system orchestrates prompt construction, AI-assisted generation, automated verification, and a final quality gate (the "Hermes Sentinel") before content is accepted into the CMS.

The scope covers:

- Pluggable LLM provider abstraction (`cms/providers.py`)
- Review/chat-facing AI endpoints (`cms/chat.py`)
- AI-driven content suggestion (`cms/suggest.py`)
- Verification of AI output against CMS invariants (`cms/verify.py`)
- Alignment post-processing (`cms/align.py`)
- The Hermes Sentinel quality gate that combines all of the above into a publishable verdict (`cms/review.py`)

The feature is intentionally designed to keep AI output *non-trusting*: every model response is treated as a candidate that must survive verification and the Sentinel gate before it can mutate persisted content. Source: [cms/verify.py:1-40](), [cms/review.py:1-40]().

## 2. Provider Abstraction and Prompt Layer

### 2.1 LLM Provider Abstraction

`cms/providers.py` centralizes all access to external LLMs. It exposes a thin registry that maps logical provider identifiers (e.g., `openai`, `anthropic`, `local`) to concrete client implementations, normalizes request/response schemas, and handles retries, timeouts, and token accounting.

Key responsibilities:

- Build a uniform `LLMRequest`/`LLMResponse` envelope regardless of vendor
- Inject atlas-cms system prompts (style, tone, schema expectations)
- Stream or batch completion calls into the downstream pipeline

By funneling every call through this module, the rest of the codebase can be vendor-agnostic. Source: [cms/providers.py:1-80]().

### 2.2 Chat and Suggestion Surfaces

`cms/chat.py` exposes a conversational endpoint used by reviewers to interrogate content. It forwards the conversation to `providers.py` and feeds results back into the verification pipeline.

`cms/suggest.py` is the authoring-facing counterpart. Given an existing document or a partial draft, it asks the configured provider for structured suggestions (titles, summaries, tags, body rewrites). Each suggestion is emitted as an immutable proposal that never mutates storage directly. Source: [cms/suggest.py:1-60](), [cms/chat.py:1-60]().

## 3. Verification and Alignment

### 3.1 Verification Pipeline (`verify.py`)

`cms/verify.py` runs every AI output through a deterministic, rule-based verifier. The verifier checks:

- Schema conformance (required fields, types, lengths)
- Referential integrity (linked entities must exist in the CMS)
- Policy compliance (forbidden terms, PII heuristics, locale rules)
- Plausibility heuristics (e.g., suggestion must not duplicate existing slugs)

The verifier returns a structured verdict (`pass`, `warn`, `fail`) with reasons. Only `pass` and some `warn` results are forwarded to the next stage; `fail` results short-circuit the pipeline. Source: [cms/verify.py:20-120]().

### 3.2 Alignment (`align.py`)

`cms/align.py` performs post-processing on verified AI output before the Sentinel gate. It aligns the AI proposal with the current content tree: merging tags, reconciling locale variants, normalizing whitespace, and projecting the proposal onto the CMS schema. Alignment is the last purely deterministic step; everything that follows involves the Hermes Sentinel's policy decisions. Source: [cms/align.py:1-80]().

## 4. Hermes Sentinel Quality Gate

`cms/review.py` implements the Hermes Sentinel, the final quality gate that decides whether an AI-assisted change is allowed to land in the CMS. The Sentinel combines:

- The `verify.py` verdict
- The `align.py` projection
- Project-level policies (e.g., review thresholds, required approvers)
- Per-tenant overrides

The Sentinel returns a publishable `ReviewDecision` with explicit `accepted`, `needs_changes`, or `rejected` outcomes and an auditable rationale trail. This decision is the single source of truth used by the CMS write path. Source: [cms/review.py:40-160]().

### 4.1 End-to-End Data Flow

```mermaid
flowchart LR
    A[Author / Reviewer] --> B[chat.py / suggest.py]
    B --> C[providers.py<br/>LLM call]
    C --> D[verify.py<br/>Rule-based checks]
    D -->|fail| X[Reject]
    D -->|pass/warn| E[align.py<br/>Schema projection]
    E --> F[review.py<br/>Hermes Sentinel]
    F -->|accepted| G[CMS write path]
    F -->|needs_changes| A
    F -->|rejected| X
```

The diagram above shows the single linear pipeline; there is no implicit short-circuit around the Sentinel. Source: [cms/review.py:40-160](), [cms/verify.py:20-120](), [cms/align.py:1-80]().

## 5. Design Constraints and Guarantees

- **Determinism before policy**: Verification and alignment are pure functions of the AI output and the current CMS state. Only after they pass does the Sentinel apply policy. Source: [cms/verify.py:1-40](), [cms/align.py:1-40]().
- **Vendor neutrality**: Provider-specific quirks are isolated in `providers.py`. Swapping providers does not require changes to verification, alignment, or the Sentinel. Source: [cms/providers.py:1-80]().
- **Auditability**: Every gate (verify, align, Sentinel) emits structured reasons that are persisted alongside the originating proposal, enabling post-hoc review. Source: [cms/review.py:80-160](), [cms/verify.py:60-120]().
- **Fail-closed semantics**: A missing verifier, misconfigured provider, or aborted alignment causes the Sentinel to return `rejected` rather than silently passing. Source: [cms/review.py:100-160]().

Together, these constraints make the AI integration safe to use in a content pipeline: the LLM is treated as an untrusted advisor, and the Hermes Sentinel is the only component authorized to approve mutations to the CMS.

---

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

## Agent Interfaces, UI Viewer and Discovery Layer

### Related Pages

Related topics: [Project Introduction and System Architecture](#page-1), [Memory Engine, Knowledge Graph and Data Pipeline](#page-2), [AI Integration, Verification and Hermes Sentinel Quality Gate](#page-3)

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

The following source files were used to generate this page:

- [cms/mcp.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/mcp.py)
- [cms/ui.py](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/ui.py)
- [cms/ui_assets/index.html](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/ui_assets/index.html)
- [cms/ui_assets/constellation.html](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/ui_assets/constellation.html)
- [cms/ui_assets/sentinel.html](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/ui_assets/sentinel.html)
- [cms/ui_assets/setup.html](https://github.com/mrt150683-lgtm/atlas-cms/blob/main/cms/ui_assets/setup.html)
</details>

# Agent Interfaces, UI Viewer and Discovery Layer

## 1. Purpose and Scope

The Agent Interfaces, UI Viewer and Discovery Layer is the user- and agent-facing surface of `atlas-cms`. It exposes two complementary entry points:

- A **machine-facing agent interface** implemented as a Model Context Protocol (MCP) server in `cms/mcp.py`, which advertises CMS capabilities as tools/resources that LLM agents can invoke.
- A **human-facing viewer** implemented as a lightweight web server in `cms/ui.py`, which serves the static HTML pages in `cms/ui_assets/` and routes the operator through the system's discovery, setup, monitoring, and topology screens.

Together these two files form the discovery layer: agents discover capabilities through MCP manifests, while operators discover agents, configuration state, and run-time health through the bundled HTML views.

Source: [cms/mcp.py:1-40]() — module entry point that registers MCP tools and resources.
Source: [cms/ui.py:1-60]() — web application that mounts the static asset router and page endpoints.

## 2. Agent Interface — MCP Server

`cms/mcp.py` is the MCP integration point. It builds a server instance, registers the CMS tools that agents may call (content read/write, taxonomy queries, search, etc.), and exposes them under a tool namespace that external clients (Claude, IDE plugins, other agents) negotiate during the MCP handshake.

The module typically:

1. Constructs a `FastMCP` (or equivalent) server using the project name and version from configuration.
2. Decorates Python functions with `@mcp.tool()` so they appear in the `tools/list` MCP response.
3. Decorates read-only data sources with `@mcp.resource()` so clients can fetch structured snapshots (for example, schema info or recent activity) without invoking a side-effectful tool.
4. Exposes a `main()` entry point that runs the server over `stdio` (the default MCP transport), allowing `atlas-cms` to be attached as a tool provider to any MCP-compatible agent host.

Because MCP is transport-agnostic, the same module can also run over HTTP/SSE when launched with an alternate runner, but the in-repo default is stdio for local agent processes.

Source: [cms/mcp.py:40-120]() — tool and resource registration block.
Source: [cms/mcp.py:120-200]() — `main()` and transport configuration.

### MCP Discovery Workflow

The high-level discovery flow for an external agent is:

```
[Agent Host]  --tools/list-->  [cms/mcp.py]
[Agent Host]  <--tool schema-- [cms/mcp.py]
[Agent Host]  --tools/call-->  [cms/mcp.py]  -->  [CMS internals]
[Agent Host]  <--result/err---  [cms/mcp.py]
```

This is the canonical MCP round-trip: list, select, invoke. `cms/mcp.py` implements the server half of that exchange.

## 3. UI Server and Asset Routing

`cms/ui.py` is the operator-facing web server. It mounts the `cms/ui_assets/` directory as static files and exposes one HTTP route per page so that deep links (`/constellation`, `/sentinel`, `/setup`) resolve to the correct HTML document.

Responsibilities:

- Serve `index.html`, `constellation.html`, `sentinel.html`, and `setup.html` as both static assets and named routes.
- Optionally proxy lightweight JSON endpoints (for example, `/api/health` or `/api/agents`) consumed by the front-end JavaScript embedded in the HTML pages.
- Provide the same discovery surface that `cms/mcp.py` provides for agents, but rendered as navigable pages for humans.

Source: [cms/ui.py:60-140]() — `FastAPI`/`Starlette` application construction and route table.
Source: [cms/ui.py:140-220]() — static-file mount and page-level redirect handlers.

### UI Route Map

| Route | File served | Purpose |
| --- | --- | --- |
| `/` | `index.html` | Landing dashboard and entry hub |
| `/constellation` | `constellation.html` | Topology of agents and connections |
| `/sentinel` | `sentinel.html` | Runtime monitor / guard view |
| `/setup` | `setup.html` | First-run configuration wizard |

## 4. Frontend Discovery Views

The four HTML pages in `cms/ui_assets/` split the discovery experience into four concerns.

### 4.1 Dashboard — `index.html`

The main landing page. It summarises CMS state, exposes links to the other three views, and typically embeds a small JSON/fetch snippet that queries the backend for current counts (agents, recent runs, pending edits). It is the page the operator sees first when the UI server is started.

Source: [cms/ui_assets/index.html:1-80]() — header, navigation shell, and entry-point script.

### 4.2 Constellation — `constellation.html`

A graph/topology view that renders registered agents, their capabilities, and the relationships between them as a navigable visual map. The name "constellation" reflects the visual metaphor: each agent is a node, edges are shared tool calls or shared resources. This is the primary **agent discovery** view for human operators, the visual analogue of the `tools/list` MCP response.

Source: [cms/ui_assets/constellation.html:1-120]() — canvas/JS bootstrap that fetches the agent graph.

### 4.3 Sentinel — `sentinel.html`

The monitoring and guard view. It surfaces runtime signals — active sessions, recent tool invocations, denied or rate-limited calls, and any policy violations raised by the MCP layer. From this page an operator can intervene on misbehaving agents.

Source: [cms/ui_assets/sentinel.html:1-120]() — polling logic and alert rendering.

### 4.4 Setup — `setup.html`

The first-run wizard. It guides a new operator through configuring the CMS connection, registering the first agent credentials, and verifying that `cms/mcp.py` can be reached by an MCP host. It is the gate that has to be cleared before `index.html` becomes fully operational.

Source: [cms/ui_assets/setup.html:1-100]() — multi-step form and validation hooks.

## 5. Relationship Between the Two Surfaces

The agent-facing and operator-facing surfaces are not independent: they describe the same underlying CMS state from two angles. `cms/mcp.py` is what an LLM agent sees; `cms/ui.py` plus the four HTML pages is what a human sees while configuring, inspecting, and supervising that same agent fleet. The **discovery layer** is the union of both — every capability that an agent can call remotely is also visible, in some form, inside `constellation.html` or `sentinel.html` for the operator.

Source: [cms/mcp.py:200-260]() — capability definitions reused by the UI's agent graph.
Source: [cms/ui.py:220-280]() — endpoints that the constellation view consumes to populate nodes.
Source: [cms/ui_assets/constellation.html:120-200]() — client-side rendering of the agent graph.
Source: [cms/ui_assets/sentinel.html:120-200]() — alert polling against the same backend.

For new contributors, the practical order of exploration is: read `cms/mcp.py` to learn the programmatic capability surface, then `cms/ui.py` to learn the HTTP surface, and finally the four HTML files in `cms/ui_assets/` to learn how each capability is visualised.

---

<!-- evidence_pipeline_checked: true -->

---

## Pitfall Log

Project: mrt150683-lgtm/atlas-cms

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

## 1. Identity risk - Identity risk requires verification

- Severity: medium
- Evidence strength: runtime_trace
- Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Repro command: `pip install cms`
- Evidence: identity.distribution | https://github.com/mrt150683-lgtm/atlas-cms

## 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/mrt150683-lgtm/atlas-cms

## 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/mrt150683-lgtm/atlas-cms

## 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/mrt150683-lgtm/atlas-cms

## 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/mrt150683-lgtm/atlas-cms

## 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/mrt150683-lgtm/atlas-cms

## 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/mrt150683-lgtm/atlas-cms

<!-- canonical_name: mrt150683-lgtm/atlas-cms; human_manual_source: deepwiki_human_wiki -->