# atlas-cms - Doramagic AI Context Pack > Positioning: a pre-install experience and judgment asset. It helps the host AI get off to a good start, but it does not mean the project has already been installed, run, or validated. ## Sufficiency Principle - **Sufficiency over compression**: The AI Context Pack should be sufficient for the host AI to understand the project's value, capability boundaries, entrypoints, risks, and evidence sources before starting work; it may be layered, but it does not aim for the shortest possible summary. - **Compression policy**: Compress only noise and duplication, never context that affects judgment or the quality of the work. ## How the Host AI Should Use This You are reading the AI Context Pack that Doramagic compiled for atlas-cms. Treat it as pre-work context: help the user understand who it fits, what it can do, how to start, what must be verified after install, and where the risks are. Do not claim that you have already installed, run, or executed the target project. ## Claim Consumption Rules - **Fact source**: Repo Evidence + Claim/Evidence Graph; the Human Wiki only supplies salience, terminology, and narrative structure. - **Minimum status for a fact**: `supported` - `supported`: May be used as a project fact, but the answer must cite the claim_id and evidence path. - `weak`: Usable only as a low-confidence lead; the user must be asked to keep verifying. - `inferred`: Usable only for risk notes or open questions; must not be packaged as a project fact. - `unverified`: Must not be used as fact; state clearly that evidence is insufficient. - `contradicted`: Must show the conflicting sources and must not force a single version on the user's behalf. ## Who It Fits Best - **Developers already using host AIs such as Claude/Codex/Cursor/Gemini**: The README or plugin config mentions multiple host AIs. Evidence: `README.md` Claim: `clm_0003` supported 0.86 ## What It Can Do - **AI Skill / Agent Instruction Asset Library** (Previewable before install): The project contains Skill or Agent instruction files that a host AI can read, useful for bringing professional workflows into hosts like Claude, Codex, or Cursor. Evidence: `SKILL.md` Claim: `clm_0001` supported 0.86 - **Command-Line Startup or Install Flow** (Verify after install): The project documentation contains runnable commands; real use requires running them in a local or host environment. Evidence: `README.md` Claim: `clm_0002` supported 0.86 ## How to Start - `pip install -e . # core (networkx, pathspec, typer)` Evidence: `README.md` Claim: `clm_0004` supported 0.86 - `pip install -e ".[anthropic]" # + Anthropic SDK for LLM summaries` Evidence: `README.md` Claim: `clm_0005` supported 0.86 - `pip install pyinstaller` Evidence: `README.md` Claim: `clm_0006` supported 0.86 - `claude mcp add cms -- cms mcp # Claude Code` Evidence: `README.md` Claim: `clm_0007` supported 0.86 - `pip install -e ".[dev]"` Evidence: `README.md` Claim: `clm_0008` supported 0.86 ## Continue-or-Stop Decision Card - **Current recommendation**: Needs admin / security approval - **Why**: Continuing may involve secrets, accounts, external services, or sensitive context; get admin or security approval first. ### 30-Second Read - **What to do now**: Needs admin / security approval - **Minimum safe next step**: Run Prompt Preview first; if credentials or an enterprise environment are involved, get approval before trialing - **Do not trust yet**: Real output quality cannot be trusted before install. - **Continuing will touch**: Command execution, Host AI configuration, Local environment or project files ### What You Can Trust Now - **Target-audience signal: Developers already using host AIs such as Claude/Codex/Cursor/Gemini** (supported): Backed by a supported claim or project evidence, but that still is not the same as real install results. Evidence: `README.md` Claim: `clm_0003` supported 0.86 - **Capability exists: AI Skill / Agent Instruction Asset Library** (supported): You can trust that the project contains signals of this capability; whether it fits your specific task still needs trial or after-install verification. Evidence: `SKILL.md` Claim: `clm_0001` supported 0.86 - **Capability exists: Command-Line Startup or Install Flow** (supported): You can trust that the project contains signals of this capability; whether it fits your specific task still needs trial or after-install verification. Evidence: `README.md` Claim: `clm_0002` supported 0.86 - **There are Quick Start / install-command signals** (supported): You can trust that the docs mention a startup or install entrypoint; do not run it directly in your primary environment because of that. Evidence: `README.md` Claim: `clm_0004` supported 0.86 ### What You Cannot Trust Yet - **Real output quality cannot be trusted before install.** (unverified): Prompt Preview can only show how it guides you; it cannot prove result quality in the real project. - **Host AI version compatibility cannot be trusted before install.** (unverified): Host loading rules and version differences across Claude, Cursor, Codex, Gemini, and others must be verified in a real environment. - **That it will not pollute your existing host AI's behavior cannot be trusted directly.** (inferred): Skill, plugin, and AGENTS/CLAUDE/GEMINI instructions may change the host AI's default behavior. Evidence: `SKILL.md` - **Safe rollback cannot be assumed by default.** (unverified): Unless the project clearly provides uninstall and recovery instructions, verify in an isolated environment first. - **After a real install, is it compatible with the user's current host AI version?** (unverified): Compatibility can only be verified in the actual host environment. - **Does the project's output quality meet the user's specific task?** (unverified): The pre-install preview can only show flow and boundaries; it cannot replace real evaluation. - **Do the install commands require network access, permissions, or global writes?** (unverified): This affects install risk in both enterprise and personal environments. Evidence: `README.md` ### What Continuing Will Touch - **Command execution**: Package managers, network downloads, the local plugin directory, project config, or the user's home directory. Why: Running the very first command can already change your environment; decide whether it is worth running first. Evidence: `README.md` - **Host AI configuration**: The plugin, Skill, or rule-loading config of hosts like Claude/Codex/Cursor/Gemini/OpenCode. Why: Host configuration changes how the AI works afterward and may conflict with the user's existing rules. Evidence: `SKILL.md` - **Local environment or project files**: Install results, plugin caches, project config, or local dependency directories. Why: The write scope and rollback path cannot be proven before install and need isolated verification. Evidence: `README.md` - **Environment variables / API keys**: Project entry docs explicitly showing API key, token, secret, or account credential configuration. Why: If a real install needs credentials, use test credentials first and go through a permission/compliance review. Evidence: `README.md`, `SKILL.md`, `cms/providers.py` - **Host AI context**: The AI Context Pack, Prompt Preview, Skill routing, risk rules, and project facts. Why: Importing context affects the host AI's later judgment, so avoid packaging unverified items as facts. ### Minimum Safe Next Steps - **Run Prompt Preview first**: Use a pre-install interactive trial to judge whether the way of working fits; it needs no authorization or environment change. (applies when: Applies to any project, especially when output quality is unknown.) - **Trial-install only in an isolated directory or a test account**: Avoid letting install commands pollute your primary host AI, real projects, or home directory. (applies when: When there are signals of command execution, plugin config, or local writes.) - **Back up your host AI configuration first**: Skill, plugin, and rule files may change the default behavior of Claude/Cursor/Codex. (applies when: When there is a plugin manifest, a Skill, or a host rule entrypoint.) - **Do not use real production credentials**: Once an environment variable / API key enters the host or toolchain, it can create account and compliance risk. (applies when: When environment signals like API, TOKEN, KEY, or SECRET appear.) - **After install, verify just one minimal task**: Verify loading, compatibility, output quality, and rollback first, then decide whether to use it deeply. (applies when: When moving from a trial into a real workflow.) ### Exit Plan - **Preserve the pre-install state**: Record the original host config and project state so you can later judge whether it is recoverable. - **Be ready to remove the host plugin / Skill / rule entrypoint**: If behavior is off after the trial install, you can restore the host AI to its pre-trial state. - **Record the install commands and written paths**: Without clear uninstall instructions, you at least need to know which directories or configs to clean up manually. - **Be ready to revoke test API keys or tokens**: If test credentials leak or are misused, you can cut losses quickly. - **If there is no rollback path, do not enter your primary environment**: No rollback is a blocker before continuing; do not proceed on trust or luck. ## What Can Only Be Previewed - Explain who the project fits and what it can do - Demonstrate a typical conversation flow based on project docs - Help the user decide whether it is worth installing or researching further ## What Must Be Verified After Install - Actually installing the Skill, plugin, or CLI - Running scripts, modifying local files, or accessing external services - Verifying real output quality, performance, and compatibility ## Boundary & Risk Decision Card - **Mistaking the pre-install preview for a real run**: The user may overestimate how much configuration, permission, and compatibility verification the project has already done. Mitigation: Clearly separate prompt_preview_can_do from runtime_required. Claim: `clm_0009` inferred 0.45 - **Command execution will modify the local environment**: Install commands may write to the user's home directory, the host plugin directory, or project configuration. Mitigation: Run in an isolated environment or a test account first. Evidence: `README.md` Claim: `clm_0010` supported 0.86 - **To confirm**: After a real install, is it compatible with the user's current host AI version?. Why: Compatibility can only be verified in the actual host environment. - **To confirm**: Does the project's output quality meet the user's specific task?. Why: The pre-install preview can only show flow and boundaries; it cannot replace real evaluation. - **To confirm**: Do the install commands require network access, permissions, or global writes?. Why: This affects install risk in both enterprise and personal environments. ## Pre-Work Working Context ### Loading Order - First read how_to_use.host_ai_instruction to establish the boundaries of this pre-install judgment asset. - Read claim_graph_summary to confirm facts come from the Claim/Evidence Graph, not the Human Wiki narrative. - Then read intended_users, capabilities, and quick_start_candidates to judge whether the user is a match. - When you need to carry out a concrete task, check role_skill_index first, then evidence_index. - For real install, file modification, network access, performance, or compatibility questions, turn to risk_card and boundaries.runtime_required. ### Task Routes - **AI Skill / Agent Instruction Asset Library**: Use role_skill_index / evidence_index to help the user pick a usable role, Skill, or workflow first. Boundary: Can be experienced via a pre-install Prompt. Evidence: `SKILL.md` Claim: `clm_0001` supported 0.86 - **Command-Line Startup or Install Flow**: State that this is an after-install capability first, then give a pre-install checklist. Boundary: Must be verified after a real install or run. Evidence: `README.md` Claim: `clm_0002` supported 0.86 ### Context Scale - Total files: 66 - Important-file coverage: 40/66 - Evidence index entries: 54 - Role / Skill entries: 7 ### Handling Insufficient Evidence - **missing_evidence**: State that evidence is insufficient and ask the user for the target file, a README section, or after-install verification records; do not fill in facts. - **out_of_scope_request**: State that the task is beyond the current AI Context Pack's evidence scope and suggest the user check the Human Manual or verify after a real install. - **runtime_request**: Provide a pre-install checklist and command sources, but do not run commands for the user or claim they have been run. - **source_conflict**: Show the conflicting sources side by side, mark them as unverified, and do not force a single version. ## Prompt Recipes ### Fit assessment - Goal: Judge whether this project fits the user's current task. - Expected output: A fit conclusion, key reasons, evidence citations, what can be previewed before install, what must be verified after install, and a next-step recommendation. ```text Based on the AI Context Pack for atlas-cms, ask me 3 necessary questions first, then judge whether it fits my task. The answer must cover: who it fits, what it can do, what it cannot do, whether it is worth installing, and where the evidence comes from. Every project fact must cite evidence_refs, source_paths, or a claim_id. ``` ### Pre-install experience - Goal: Let the user feel the core workflow before installing, while avoiding packaging the preview as real capability or a marketing promise. - Expected output: An experience script with boundary labels, an after-install verification checklist, and a cautious recommendation; with no real-run promises or strong marketing language. ```text Treat atlas-cms as a pre-install experience asset, not an already-installed tool or a real runtime environment. Output exactly four parts: 1. Ask me 3 necessary questions first. 2. Give an "experience script": use the three labels [Previewable before install], [Must verify after install], and [Insufficient evidence] to show how it might guide the workflow. 3. Give an after-install verification checklist: list which capabilities can only be confirmed after a real install, real host loading, and a real project run. 4. Give a cautious recommendation: only "worth researching/trialing further", "add information before deciding", or "not recommended to continue"; do not endorse the project. Hard boundaries: - Do not claim you have installed, run, executed tests, modified files, or produced real results. - Do not write promise-like phrasing such as "auto-adapts", "guarantees passing", "perfect fit", or "strongly recommend installing". - If you describe how it works after install, you must use a conditional such as "if installed successfully and the host loads the Skill correctly, it might...". - The experience script may only be written as "example lines / hypothetical flow": use "might ask / might suggest / might show", not "has written, has generated, has passed, is running, is generating". - Prompt Preview does not hand out install commands; if the user is ready to trial, only prompt them to read Quick Start and the Risk Card first and to verify in an isolated environment. - Every project fact must come from a supported claim, evidence_refs, or source_paths; inferred/unverified items can only be risks or open questions. ``` ### Role / Skill selection - Goal: Pick the best-matching asset from the project's roles or Skills. - Expected output: A list of candidate roles or Skills, each with an applicable scenario, evidence paths, risk boundary, and whether after-install verification is needed. ```text Read role_skill_index and recommend 3-5 of the most relevant roles or Skills for my target task. For each recommendation, state the applicable scenario, likely output, risk boundary, and evidence_refs. ``` ### Risk pre-check - Goal: Identify environment, permission, rule-conflict, and quality risks before installing or adopting. - Expected output: A checklist of environment, permission, dependency, license, host-conflict, quality risk, and unknown items. ```text Based on risk_card, boundaries, and quick_start_candidates, give me a pre-install risk pre-check list. Do not run commands for me; only explain what I should check, why, and what impact a failure would have. ``` ### Host AI kickoff instruction - Goal: Turn the project context into a host AI instruction for the start of a conversation. - Expected output: A pre-work instruction with clear boundaries and clear evidence citations, suitable to copy to a host AI. ```text Based on the AI Context Pack for atlas-cms, generate a pre-work instruction I can paste to my host AI. This instruction must obey not_runtime=true and must not claim the project has been installed, run, or produced real results. ``` ## Role / Skill Index - Indexed 7 role / Skill / project-doc entries. - **Install** (project_doc): Every codebase, mapped. Ground truth for AI agents. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `README.md` - **Atlas operations — this machine's setup** (project_doc): Atlas operations — this machine's setup Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/ATLAS_OPERATIONS.md` - **atlas** (skill): - Activation hint: When the user's task is highly relevant to the workflow described by “atlas”, use it for a pre-install experience first, then decide whether to install. Evidence: `SKILL.md` - **Codebase Memory System CMS — Design Spec & Build Plan** (project_doc): Codebase Memory System CMS — Design Spec & Build Plan Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `codebase_memory_system_design_spec.md` - **Hermes Sentinel** (project_doc): Hermes Sentinel is CMS's built-in bug-finding, feature-auditing, workflow-verification and completion-gate system. It inspects the codebase the memory layer describes and answers one question honestly: is what we claim built actually complete, wired, tested and consistent? Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `docs/HERMES_SENTINEL.md` - **Contributors and provenance** (project_doc): Atlas is the result of a collaborative development process involving human direction and several AI systems. This document records that process without substituting acknowledgements for Git's authorship history. Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `CONTRIBUTORS.md` - **Codebase Memory System - Build Updates & Living Notes** (project_doc): Codebase Memory System - Build Updates & Living Notes Activation hint: Reference this when the user needs to understand the project's structure, install path, or boundaries. Evidence: `updates.md` ## Evidence Index - Indexed 54 evidence entries. - **Install** (documentation): Every codebase, mapped. Ground truth for AI agents. Evidence: `README.md` - **Atlas operations — this machine's setup** (documentation): Atlas operations — this machine's setup Evidence: `docs/ATLAS_OPERATIONS.md` - **▲ Atlas — Codebase Memory System: the agent's manual** (skill_instruction): ▲ Atlas — Codebase Memory System: the agent's manual Evidence: `SKILL.md` - **License** (source_file): GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 Evidence: `LICENSE` - **Codebase Memory System CMS — Design Spec & Build Plan** (documentation): Codebase Memory System CMS — Design Spec & Build Plan Evidence: `codebase_memory_system_design_spec.md` - **Hermes Sentinel** (documentation): Hermes Sentinel is CMS's built-in bug-finding, feature-auditing, workflow-verification and completion-gate system. It inspects the codebase the memory layer describes and answers one question honestly: is what we claim built actually complete, wired, tested and consistent? Evidence: `docs/HERMES_SENTINEL.md` - **Init** (source_file): all = "CodebaseMemory", "QueryResult", "FileRecord", "scan" version = "0.1.0" Evidence: `cms/__init__.py` - **untracked, not-ignored files show up as "?? path" in porcelain status** (source_file): ALIGN DIR = "align" CRITICAL = "critical" ⋮---- def git changed files root: Path, base: str = "HEAD" - list str ⋮---- root = root.resolve ⋮---- prefix = git root, "rev-parse", "--show-prefix" or "" .strip ⋮---- raw: set str = set tracked = git root, "diff", "--name-only", base ⋮---- untracked, not-ignored files show up as "?? path" in porcelain status status = git root, "status", "--porcelain", "--untracked-files=all" ⋮---- path = line 3: .strip if len line 3 else "" ⋮---- out: set str = set ⋮---- path = path.replace "\\", "/" .strip '"' ⋮---- path = path len prefix : ⋮---- ── graph helpers ─────────────────────────────────────────────────────────── ⋮---- def touched features graph: nx.DiGr… Evidence: `cms/align.py` - **@memory:feature:CodebaseChat** (source_file): CHAT MAX TOKENS = 1600 HISTORY TURNS = 6 TRANSCRIPT = "chat.jsonl" ⋮---- CHAT PROMPT = """You are Atlas, the memory layer of the codebase "{project}", talking to its OWNER. ⋮---- class ChatError RuntimeError ⋮---- def trim text, n=400 ⋮---- text = str text or "" .strip ⋮---- @memory:feature:CodebaseChat @memory:connects:QueryEngine, FeatureTracing, FeatureExpectationReview, HermesSentinel @memory:summary:Assembles the cross-layer evidence pack one question needs — ranked hits, matched feature traces+reviews, app review, Sentinel gate, pipeline state — for grounded plain-language answers. def build evidence root: Path, question: str - tuple dict, list str ⋮---- """Evidence pack + touched nod… Evidence: `cms/chat.py` - **Config** (source_file): MEMORY DIR NAME = ".memory" CMSIGNORE FILENAME = ".cmsignore" ⋮---- DEFAULT IGNORES: list str = ⋮---- LANGUAGE BY EXTENSION: dict str, str = { ⋮---- USER CONFIG PATH = Path.home / ".cms" / "config.json" ⋮---- CONFIG KEYS: dict str, str = { ⋮---- def load user config - dict ⋮---- def save user config cfg: dict - None ⋮---- def apply user config - None ⋮---- cfg = load user config ⋮---- value = cfg.get key ⋮---- ENV PROVIDER = "CMS PROVIDER" ⋮---- ANTHROPIC MODEL = os.environ.get "CMS ANTHROPIC MODEL", "claude-haiku-4-5-20251001" OPENAI BASE URL = os.environ.get "CMS OPENAI BASE URL", "http://localhost:11434/v1" OPENAI MODEL = os.environ.get "CMS OPENAI MODEL", "llama3.1" ⋮---- MAX TOKENS = 1… Evidence: `cms/config.py` - **── 1. declared features anchors ─────────────────────────────────────────** (source_file): MAX FLOW DEPTH = 6 MAX FLOWS PER FEATURE = 8 ⋮---- @dataclass class Feature ⋮---- name: str description: str = "" source: str = "declared" members: list str = field default factory=list entry points: list str = field default factory=list flows: list list dict = field default factory=list connects: list str = field default factory=list narrative: str = "" narrative provider: str = "" ⋮---- @property def node id self - str ⋮---- ── 1. declared features anchors ───────────────────────────────────────── ⋮---- def collect declared features graph: nx.DiGraph - dict str, Feature ⋮---- features: dict str, Feature = {} ⋮---- anchors = attrs.get "anchors" or {} ⋮---- feat = features.setdefault name,… Evidence: `cms/features.py` - **-- calls ---------------------------------------------------------** (source_file): @dataclass class Component ⋮---- kind: str name: str qualname: str start line: int end line: int signature: str = "" docstring: str = "" bases: list str = field default factory=list parent scope: str None = None qualname of enclosing class/func, None if top-level parent is class: bool = False ⋮---- @dataclass class FileInfo ⋮---- record: FileRecord components: list Component = field default factory=list imported modules: list str = field default factory=list full dotted names alias to module: dict str, str = field default factory=dict "np" - "numpy" from imports: dict str, tuple str, str = field default factory=dict calls: list tuple str, tuple = field default factory=list anchor groups: li… Evidence: `cms/graph_builder.py` - **Intent** (source_file): def infer goal root: Path - tuple str, str ⋮---- branch = git root, "rev-parse", "--abbrev-ref", "HEAD" or "" .strip ⋮---- readable = branch.rsplit "/", 1 -1 .replace "-", " " .replace " ", " " .strip ⋮---- subject = git root, "log", "-1", "--format=%s" or "" .strip ⋮---- def capture intent root: Path, goal: str None = None, base: str = "HEAD", top k: int = 8 - dict ⋮---- root = root.resolve source = "explicit" ⋮---- goal = " unstated " source = "none" ⋮---- memory dir = root / config.MEMORY DIR NAME mem = CodebaseMemory.load memory dir / "graph.json" pack = build task pack mem, root, goal, top k=top k Evidence: `cms/intent.py` - **Never create .memory/ in a project that has no memory layer yet —** (source_file): PROTOCOL VERSION = "2024-11-05" HISTORY FOR MCP = 6 ⋮---- TOOLS = ⋮---- def discover root start: Path - Path ⋮---- class MCPServer ⋮---- def init self, root: Path - None ⋮---- def memory self - CodebaseMemory ⋮---- mtime = self.graph path.stat .st mtime ⋮---- def log self, tool: str, nodes: list str , label: str = "" - None ⋮---- Never create .memory/ in a project that has no memory layer yet — the feed is cosmetic and must not scribble on un-mapped repos. ⋮---- ── tool implementations ──────────────────────────────────────────── ⋮---- def query codebase self, query: str, top k: int = 5 - list dict ⋮---- def get file summary self, path: str - dict ⋮---- graph = self.memory .graph node id =… Evidence: `cms/mcp.py` - **Providers** (source_file): class SummaryProvider Protocol ⋮---- name: str ⋮---- def summarize self, prompt: str, context: dict - str: ... ⋮---- class AnthropicProvider ⋮---- name = "anthropic" ⋮---- def init self, model: str None = None - None ⋮---- def summarize self, prompt: str, context: dict - str ⋮---- kwargs = {} ⋮---- response = self. client.messages.create ⋮---- class OpenAICompatProvider ⋮---- name = "openai" ⋮---- def init self, base url: str None = None, model: str None = None - None ⋮---- body = { ⋮---- payload = json.dumps body .encode "utf-8" request = urllib.request.Request ⋮---- data = json.loads resp.read .decode "utf-8" ⋮---- class MockProvider ⋮---- name = "mock" ⋮---- path = context.get "path", "?… Evidence: `cms/providers.py` - **Review** (source_file): VERDICTS = "aligned", "partial", "drift", "unverified" ⋮---- FEATURE REVIEW PROMPT = """You are reviewing one feature of an application on behalf of its END USER. ⋮---- APP REVIEW PROMPT = """You are writing the END USER a top-level review of their application, based on per-feature reviews. ⋮---- def app context root: Path - str ⋮---- readme = root / "README.md" ⋮---- lines = readme.read text encoding="utf-8", errors="replace" .splitlines ⋮---- def flow lines feat: dict - str ⋮---- out = ⋮---- def member summaries graph: nx.DiGraph, feat: dict - str ⋮---- a = graph.nodes m head = a.get "summary" or a.get "docstring" or "" .strip .splitlines ⋮---- def parse json raw: str - dict None ⋮---- ma… Evidence: `cms/review.py` - **prune ignored / out-of-scope directories in place so os.walk skips them** (source_file): @dataclass class FileRecord ⋮---- rel path: str abs path: str size bytes: int line count: int mtime: float language: str ⋮---- def to dict self - dict ⋮---- def load ignore spec root: Path - pathspec.PathSpec ⋮---- lines = list DEFAULT IGNORES gitignore = root / ".gitignore" ⋮---- cmsignore = root / CMSIGNORE FILENAME ⋮---- def count lines path: Path - int ⋮---- content = f.read ⋮---- def scan root: Path str - list FileRecord ⋮---- root = Path root .resolve spec = load ignore spec root scope = load scope root records: list FileRecord = ⋮---- dir rel = Path dirpath .relative to root .as posix prefix = "" if dir rel == "." else dir rel + "/" prune ignored / out-of-scope directories in place s… Evidence: `cms/scanner.py` - **Semantic State** (source_file): SCHEMA VERSION = 1 STATE FILENAME = "semantic state.json" STAGES = "summaries", "features", "review", "suggestions" ⋮---- DISCOVERY SCHEMA VERSION = 1 ⋮---- NEVER RUN = {"status": "never run"} ⋮---- def state path memory dir: Path - Path ⋮---- def load state memory dir: Path - dict ⋮---- def stage state: dict, name: str - dict ⋮---- def record stage memory dir: Path, name: str, fields - dict ⋮---- state = load state memory dir ⋮---- stages = state.setdefault "stages", {} record = dict fields ⋮---- def atomic write json dest: Path, payload - None ⋮---- tmp = dest.with suffix f".{uuid.uuid4 .hex}.tmp" ⋮---- def sha items - str ⋮---- def discovery input hash graph - str ⋮---- files = sorted an… Evidence: `cms/semantic_state.py` - **Suggest** (source_file): KINDS = "new-feature", "improvement", "hardening" ⋮---- SUGGEST PROMPT = """You are a pragmatic principal engineer planning the next moves for this app. ⋮---- def evidence graph: nx.DiGraph, root: Path - dict ⋮---- features = get features graph feature lines = untested = ⋮---- r = f.get "review" or {} gaps = "; ".join r.get "gaps" or :2 or "none noted" tests = len f.get "exercised by" or ⋮---- hot = sorted hotspots = ", ".join f"{p} {c} commits " for p, c, in hot or " no git history " ⋮---- coupling = ", ".join ⋮---- readme = root / "README.md" app context = "\n".join ⋮---- def sanitize item: dict - dict None ⋮---- title = str item.get "title", "" .strip ⋮---- value = max 1, min 5, int item… Evidence: `cms/suggest.py` - **@memory:feature:SummaryGenerator** (source_file): PROMPT TEMPLATE = """You are an expert senior software architect creating a LOW-RESOLUTION structural map of code for another AI agent. ⋮---- ANCHORS PROMPT SECTION = """ ⋮---- def anchor prompt lines context: dict - str ⋮---- lines: list str = ⋮---- def truncate source source: str, budget: int = config.MAX SOURCE CHARS - str ⋮---- head = int budget 2 / 3 tail = budget - head ⋮---- def file context graph: nx.DiGraph, file id: str - dict ⋮---- attrs = graph.nodes file id components = ⋮---- c = graph.nodes child ⋮---- imports = sorted ⋮---- def component slice summary: str, name: str - str ⋮---- lines = summary.splitlines pattern = re.compile rf"\b{re.escape name }\b" ⋮---- block = line.strip… Evidence: `cms/summarizer.py` - **── Hermes Sentinel API ──────────────────────────────────────** (source_file): ASSETS DIR = Path sys. MEIPASS / "cms" / "ui assets" ⋮---- ASSETS DIR = Path file .parent / "ui assets" ⋮---- class MemoryCache ⋮---- def init self, graph path: Path - None ⋮---- def get self - CodebaseMemory None ⋮---- mtime = self.graph path.stat .st mtime ⋮---- def make handler root: Path, cache: MemoryCache ⋮---- memory dir = root / config.MEMORY DIR NAME ⋮---- sentinel state = {"running": False, "error": "", "finished at": 0.0} sentinel lock = threading.Lock build state = {"running": False, "error": "", "message": "", "finished at": 0.0} build lock = threading.Lock ⋮---- pkg dir = Path file .resolve .parent ⋮---- def newest code mtime - float ⋮---- boot code mtime = newest code mtime ⋮… Evidence: `cms/ui.py` - **Verify** (source_file): COVERAGE RC = """\ ⋮---- def python - str ⋮---- def context to pytest id context: str, known files: list str - str None ⋮---- context = context.split " ", 1 0 .strip ⋮---- parts = context.split "." ⋮---- suffix = "/".join parts :cut + ".py" match = next ⋮---- tail = "::".join parts cut: ⋮---- def run coverage root: Path, pytest args: list str None = None - dict None ⋮---- """Run pytest under coverage with per-test contexts; return coverage JSON.""" ⋮---- rc = Path tmp / ".coveragerc" ⋮---- data file = Path tmp / ".coverage" json file = Path tmp / "coverage.json" env args = "--rcfile", str rc , "--data-file", str data file run = subprocess.run ⋮---- export = subprocess.run ⋮---- def map test… Evidence: `cms/verify.py` - **Pyproject** (source_file): build-system requires = "setuptools =68" build-backend = "setuptools.build meta" Evidence: `pyproject.toml` - **Init** (source_file): SEVERITIES = "critical", "high", "medium", "low", "info" FINDING STATUSES = ⋮---- ACTIVE STATUSES = "open", "acknowledged", "fixed pending verification" ⋮---- severity = "info" fingerprint = hashlib.sha1 Evidence: `cms/sentinel/__init__.py` - **reportMeta { margin: 10px 0 4px; }** (source_file): Atlas · Discovery :root { --bg: 101114; --panel: 17181c; --line: 26272c; --ink: d7d9de; --ink-2: 9a9da6; --ink-3: 6b6e78; --accent: 3987e5; --amber: c98500; --green: 199e70; --red: e05252; --font: "Segoe UI", system-ui, sans-serif; --mono: "Cascadia Code", Consolas, monospace; } { box-sizing: border-box; margin: 0; } body { background: var --bg ; color: var --ink ; font: 13.5px/1.55 var --font ; } header { display: flex; align-items: center; gap: 14px; padding: 10px 20px; border-bottom: 1px solid var --line ; background: var --panel ; } header .mark { font-weight: 700; letter-spacing: .22em; } header .logo { width: 22px; height: 22px; } .lg-peak { fill: none; stroke: var --accent ; stroke-w… Evidence: `cms/ui_assets/constellation.html` - **app {** (source_file): Atlas — Codebase Map :root { --bg: 0d0d0d; --surface: 1a1a19; --surface-2: 141413; --border: rgba 255,255,255,0.08 ; --border-strong: rgba 255,255,255,0.14 ; --ink: ffffff; --ink-2: c3c2b7; --ink-3: 898781; --accent: 3987e5; --grid: 2c2c2a; --radius: 8px; --font: system-ui, -apple-system, "Segoe UI", sans-serif; --mono: ui-monospace, "Cascadia Code", "Consolas", monospace; } { box-sizing: border-box; margin: 0; padding: 0; } html, body { height: 100%; } body { background: var --bg ; color: var --ink-2 ; font: 13px/1.5 var --font ; -webkit-font-smoothing: antialiased; overflow: hidden; } ::selection { background: rgba 57,135,229,0.35 ; } ::-webkit-scrollbar { width: 10px; height: 10px; } ::-… Evidence: `cms/ui_assets/index.html` - **app { display: grid; height: 100vh; grid-template-rows: 52px 1fr; grid-template-columns: 218px 1fr; }** (source_file): Atlas — Hermes Sentinel :root { --bg: 0d0d0d; --surface: 1a1a19; --surface-2: 141413; --border: rgba 255,255,255,0.08 ; --border-strong: rgba 255,255,255,0.14 ; --ink: ffffff; --ink-2: c3c2b7; --ink-3: 898781; --accent: 3987e5; --radius: 8px; --font: system-ui, -apple-system, "Segoe UI", sans-serif; --mono: ui-monospace, "Cascadia Code", "Consolas", monospace; --sev-critical: ff6369; --sev-high: ffa14f; --sev-medium: e2c341; --sev-low: 6ca6f0; --sev-info: 898781; --ok: 4fc26b; } { box-sizing: border-box; margin: 0; padding: 0; } html, body { height: 100%; } body { background: var --bg ; color: var --ink-2 ; font: 13px/1.5 var --font ; -webkit-font-smoothing: antialiased; overflow: hidden; }… Evidence: `cms/ui_assets/sentinel.html` - **tree { max-height:52vh; overflow:auto; border:1px solid var --border ; border-radius:8px; padding:8px 6px; background:v…** (source_file): Atlas — Setup :root { --bg: 0d0d0f; --surface: 151517; --surface-2: 1b1b1f; --border: 2a2a30; --ink: ececef; --ink-2: b9b9c0; --ink-3: 7a7a84; --accent: 3987e5; --mono:ui-monospace,"Cascadia Code",Consolas,monospace; --font:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif; --ok: 199e70; --warn: c98500; } { box-sizing:border-box; } body { margin:0; background:var --bg ; color:var --ink-2 ; font:14.5px/1.6 var --font ; } a { color:var --accent ; text-decoration:none; } header { display:flex; align-items:center; gap:9px; padding:14px 22px; border-bottom:1px solid var --border ; } .logo { width:22px; height:22px; } .logo .lg-peak { fill:none; stroke:var --accent ; stroke-width:1.8;… Evidence: `cms/ui_assets/setup.html` - **Contributors and provenance** (documentation): Atlas is the result of a collaborative development process involving human direction and several AI systems. This document records that process without substituting acknowledgements for Git's authorship history. Evidence: `CONTRIBUTORS.md` - **Codebase Memory System - Build Updates & Living Notes** (documentation): Codebase Memory System - Build Updates & Living Notes Evidence: `updates.md` - **Feature Ledger** (structured_config): { "about": "Feature completion ledger audited by Hermes Sentinel cms sentinel . Statuses: not started in progress blocked complete.", "features": { "feature": "ActivityPulse", "status": "in progress", "evidence": { "files": "cms/activity.py" , "database": ".memory/graph.json" , "api": , "ui": , "tests": , "manual verification": "" }, "known limitations": "no verifying tests mapped yet" , "last verified": "2026-07-05" }, { "feature": "AgentMemoryAccess", "status": "in progress", "evidence": { "files": "cms/mcp.py" , "database": ".memory/graph.json" , "api": , "ui": , "tests": , "manual verification": "" }, "known limitations": "no verifying tests mapped yet" , "last verified": "2026-07-05" }… Evidence: `docs/feature_ledger.json` - **Sentinel.Config** (structured_config): { "fail on": "critical" , "warn on": "high", "medium" , "ignore paths": } Evidence: `sentinel.config.json` - **Project-specific ignore patterns for CMS gitignore syntax .** (source_file): Project-specific ignore patterns for CMS gitignore syntax . These extend the built-in defaults in cms/config.py. Evidence: `.cmsignore` - **Python** (source_file): Python pycache / .pyc .venv/ .egg-info/ .pytest cache/ .coverage Evidence: `.gitignore` - **Cms** (source_file): @echo off REM Atlas launcher - runs the CLI via the repo's .venv, falling back to the REM python on PATH AVG blocks the unsigned CMS.exe, so we run from source . REM Double-click for the app UI , or: CMS.bat query "..." CMS.bat align "..." etc. setlocal set "CMS PY=%~dp0.venv\Scripts\python.exe" if not exist "%CMS PY%" where python nul 2 nul if errorlevel 1 echo Atlas setup incomplete: no .venv at "%~dp0.venv" and no python on PATH. echo Recreate it with: py -3.11 -m venv .venv ^&^& .venv\Scripts\pip install -e . dev,anthropic exit /b 9009 set "CMS PY=python" "%CMS PY%" -m cms.cli % set "RC=%ERRORLEVEL%" REM Pause only on double-click no args so the window stays readable on errors; REM neve… Evidence: `CMS.bat` - **Activity** (source_file): ACTIVITY FILE = "activity.jsonl" MAX BYTES = 128 000 KEEP LINES = 120 MAX NODES PER EVENT = 40 ⋮---- def log activity memory dir: Path, tool: str, nodes: list str , label: str = "" - None ⋮---- path = memory dir / ACTIVITY FILE entry = { ⋮---- lines = path.read text encoding="utf-8" .splitlines -KEEP LINES: ⋮---- def read activity memory dir: Path, since: float - list dict ⋮---- events = ⋮---- entry = json.loads line Evidence: `cms/activity.py` - **App** (source_file): def workspace config path - Path ⋮---- def load workspace root - Path None ⋮---- ws = workspace config path ⋮---- saved = Path json.loads ws.read text encoding="utf-8" "root" ⋮---- def save workspace root root: Path - None ⋮---- def first run setup echo - Path None ⋮---- chosen = pick folder "Choose the codebase folder for Atlas" ⋮---- root = Path chosen .expanduser .resolve ⋮---- raw = input "\nProject root directory or Q to quit : " .strip .strip '"' .strip "'" ⋮---- root = Path raw .expanduser ⋮---- root = root.resolve found = len scan root ⋮---- def resolve root explicit: Path None, echo=print - Path None ⋮---- """Explicit --root wins; else the saved workspace the last codebase you chos… Evidence: `cms/app.py` - **── generation ───────────────────────────────────────────────────────────** (source_file): BRAINSTORM DIR = Path.home / ".cms" / "brainstorm" IDEAS PER BATCH = 10 GEN MAX TOKENS = 1500 DEFAULT TEMPERATURE = 1.0 ⋮---- GEN PROMPT = """You are a prolific concept generator producing GENUINELY NEW ideas for one builder. ⋮---- MODE RANDOM = """MODE: unconstrained. Ideas must be NEW CONCEPTS — unrelated to the ⋮---- MODE PROJECT = """MODE: grounded in the project "{name}". ⋮---- class BrainstormError RuntimeError ⋮---- def read name: str, default ⋮---- def write name: str, payload - None ⋮---- def load ideas - dict ⋮---- def load goals - list dict ⋮---- def add goal text: str - list dict ⋮---- text = text or "" .strip ⋮---- goals = load goals gid = hashlib.sha1 text.lower .encode .hexdi… Evidence: `cms/brainstorm.py` - **Bundle** (source_file): BUNDLE SUFFIX = ".cmsbundle" ⋮---- def version - str ⋮---- def default bundle name root: Path - str ⋮---- """Zip the generated memory + optional source snapshot into a bundle.""" root = Path root .resolve memory dir = root / config.MEMORY DIR NAME ⋮---- out path = Path out path .resolve if out path else Path.cwd / default bundle name root ⋮---- out path = out path.with suffix BUNDLE SUFFIX ⋮---- source records = ⋮---- source records = scan root ⋮---- manifest = { ⋮---- mem count = 0 ⋮---- arc = Path config.MEMORY DIR NAME / p.relative to memory dir .as posix ⋮---- sp = scope path root ⋮---- def read manifest bundle path: Path - dict ⋮---- def open bundle bundle path: Path, dest: Path, echo=… Evidence: `cms/bundle.py` - **Walk up to the nearest mapped project a global MCP config launches us** (source_file): app = typer.Typer ⋮---- @app.callback invoke without command=True def main ctx: typer.Context - None ⋮---- RootOption = typer.Option Path "." , "--root", "-r", help="Project root to analyse." ⋮---- config app = typer.Typer ⋮---- """Store a setting, e.g.: cms config set anthropic api key sk-ant-...""" key = key.lower ⋮---- cfg = config.load user config ⋮---- @config app.command "show" def config show - None ⋮---- shown = f"{value :8 }...{value -4: }" if "key" in key and len str value 14 else value ⋮---- @config app.command "path" def config path - None ⋮---- def memory dir root: Path - Path ⋮---- @app.command def scan root: Path = RootOption - None ⋮---- root = root.resolve records = scan di… Evidence: `cms/cli.py` - **Exporter** (source_file): INDEX TEMPLATE = """ Codebase Memory .memory/ ⋮---- def export graph graph: nx.DiGraph, memory dir: Path - Path ⋮---- out = memory dir / "graph.json" ⋮---- def export summaries graph: nx.DiGraph, memory dir: Path - int ⋮---- summaries dir = memory dir / "summaries" count = 0 ⋮---- rel = attrs "path" target = summaries dir / rel + ".md" ⋮---- provider = attrs.get "summary meta" or {} .get "provider", "?" ⋮---- def export features graph: nx.DiGraph, memory dir: Path - int ⋮---- features = get features graph ⋮---- features dir = memory dir / "features" ⋮---- toc = " Feature Traces\n" ⋮---- safe = "".join c if c.isalnum or c in "- " else " " for c in f "name" member lines = "\n".join f"- {m} "… Evidence: `cms/exporter.py` - **── fusion synthesis ─────────────────────────────────────────────────────** (source_file): REGISTRY PATH = Path.home / ".cms" / "projects.json" FUSION DIR = Path.home / ".cms" / "fusion" FUSION MAX TOKENS = 4000 ⋮---- FUSION PROMPT = """You are a principal architect reviewing SEVERAL separate codebases owned by one team. ⋮---- class FusionError RuntimeError ⋮---- REFINE PROMPT = """You are refining an existing cross-project fusion report according to the owner's direction. ⋮---- def load registry - dict ⋮---- def register project root: Path - None ⋮---- root = Path root .resolve tmp = str Path tempfile.gettempdir .resolve .lower ⋮---- reg = load registry projects = reg.setdefault "projects", {} ⋮---- def build card root: Path - dict ⋮---- memory dir = root / config.MEMORY DIR NAM… Evidence: `cms/fuse.py` - **only hidden coupling: no import relationship in either direction** (source_file): MAX COMMITS = 1000 MAX FILES PER COMMIT = 30 MIN COCHANGES = 3 MAX COCHANGE EDGES = 40 ⋮---- def git root: Path, args: str - str None ⋮---- result = subprocess.run ⋮---- def collect git history root: Path - dict None ⋮---- prefix = git root, "rev-parse", "--show-prefix" or "" .strip log = git ⋮---- files: dict str, dict = defaultdict pair counts: Counter = Counter commit files: list str = author = "" timestamp = 0.0 ⋮---- def flush commit - None ⋮---- unique = sorted set commit files ⋮---- timestamp = float ts ⋮---- parts = line.split "\t" ⋮---- path = path len prefix : stats = files path ⋮---- cochanges = ⋮---- def enrich graph with git graph: nx.DiGraph, root: Path - dict None ⋮---- histo… Evidence: `cms/githistory.py` - **Impact** (source_file): @dataclass class Impact ⋮---- target: str functions: list str = field default factory=list files: list str = field default factory=list features: list str = field default factory=list tests: list str = field default factory=list ⋮---- @property def total self - int ⋮---- def resolve target graph: nx.DiGraph, target: str - str None ⋮---- nid = f"{kind}:{path}::{qual}" ⋮---- matches = ⋮---- def is test path: str - bool ⋮---- name = path.rsplit "/", 1 -1 ⋮---- def analyze impact graph: nx.DiGraph, target: str - Impact None ⋮---- node id = resolve target graph, target ⋮---- affected: set str = set frontier = node id ⋮---- current = frontier.pop ⋮---- attrs = graph.nodes current ⋮---- file id =… Evidence: `cms/impact.py` - **named ES import bindings: import Default, { a, b as c } from './x'** (source_file): CLASS = re.compile r"^\s ?:export\s+ ? ?:default\s+ ? ?:abstract\s+ ?class\s+ A-Za-z $ \w$ " TYPEISH = re.compile r"^\s ?:export\s+ ? ?:default\s+ ? ?:declare\s+ ? ?:interface type enum \s+ A-Za-z $ \w$ " FUNC = re.compile r"^\s ?:export\s+ ? ?:default\s+ ? ?:async\s+ ?function\s \ ?\s A-Za-z $ \w$ " CONST = re.compile r"^\s ?:export\s+ ? ?:default\s+ ? ?:const let var \s+ A-Za-z $ \w$ \s ?::\s ^= +? ?=\s . $" ⋮---- IMPORT FROM = re.compile r""" ?:import export \b ^;'" ?\bfrom\s '" ^'" + '" """ IMPORT BARE = re.compile r"""^\s import\s+ '" ^'" + '" """, re.M REQUIRE = re.compile r"""\brequire\s \ \s '" ^'" + '" \s \ """ DYNIMPORT = re.compile r"""\bimport\s \ \s '" ^'" + '" \s \ """ ⋮---- L… Evidence: `cms/js_parser.py` - **-- persistence ----------------------------------------------------** (source_file): STOPWORDS = { ⋮---- def tokenize text: str - list str ⋮---- def name tokens name: str - set str ⋮---- """Split snake case and camelCase identifiers into searchable tokens.""" parts = re.split r" \W +", name tokens: set str = {name.lower } ⋮---- @dataclass class QueryResult ⋮---- node id: str kind: str name: str path: str start line: int None end line: int None score: float summary: str = "" anchors: dict = field default factory=dict calls: list str = field default factory=list called by: list str = field default factory=list ⋮---- @property def lines self - str ⋮---- class CodebaseMemory ⋮---- def init self, graph: nx.DiGraph - None ⋮---- -- persistence -------------------------------------… Evidence: `cms/memory.py` - **-- mutations --------------------------------------------------------** (source_file): NOTES FILE = "notes.json" COLORS = "amber", "blue", "green", "purple", "rose" MAX QUOTE = 2000 MAX NOTE = 4000 ⋮---- def now iso - str ⋮---- class NotesStore ⋮---- def init self, memory dir: Path - None ⋮---- def read self - list dict ⋮---- data = json.loads self.path.read text encoding="utf-8" ⋮---- def write self, notes: list dict - None ⋮---- tmp = self.path.with suffix ".tmp" ⋮---- def all self - list dict ⋮---- def for path self, path: str - list dict ⋮---- def counts self - dict str, int ⋮---- out: dict str, int = {} ⋮---- -- mutations -------------------------------------------------------- ⋮---- entry = { notes = self. read ⋮---- def delete self, note id: str - bool ⋮---- kept = n f… Evidence: `cms/notes.py` - **Picker** (source_file): def pick folder title: str = "Choose the codebase folder for Atlas" - str None ⋮---- root = tk.Tk ⋮---- path = filedialog.askdirectory title=title Evidence: `cms/picker.py` - **Prompt Export** (source_file): def slug text: str - str ⋮---- def build task pack mem: CodebaseMemory, root: Path, task: str, top k: int = 8 - dict ⋮---- graph = mem.graph hits = mem.query intent task, top k=top k ⋮---- targets = feature names: set str = set files seen: set str = set ⋮---- entry = { node = graph.nodes.get h.node id, {} ⋮---- features = ⋮---- impact = None primary = next h for h in hits if h.kind in "func", "class" , None or \ ⋮---- result = analyze impact graph, primary.node id ⋮---- impact = { ⋮---- words = set re.findall r" a-z0-9 +", task.lower suggestions = ⋮---- text = s "title" + " " + s "description" .lower ⋮---- def render prompt pack: dict - str ⋮---- lines = ⋮---- loc = f"{t 'path' }:{t 'lines'… Evidence: `cms/prompt_export.py` - **Scope** (source_file): SCOPE FILENAME = ".cmsscope.json" ⋮---- def scope path root: Path - Path ⋮---- def norm x: str - str ⋮---- def load scope root: Path - set str None ⋮---- """Return the include set dir prefixes end in / , or None for 'all'.""" p = scope path root ⋮---- data = json.loads p.read text encoding="utf-8" ⋮---- includes = { norm x for x in data.get "include" or if str x .strip } ⋮---- def save scope root: Path, includes: list str - Path ⋮---- norm = sorted { norm x for x in includes if str x .strip } - {""} ⋮---- def clear scope root: Path - bool ⋮---- def file in scope rel: str, scope: set str None - bool ⋮---- rel = rel.replace "\\", "/" ⋮---- def build dir tree root: Path - dict ⋮---- """Nested… Evidence: `cms/scope.py` - **Scout** (source_file): SCOUT DIR = Path.home / ".cms" / "scout" PLAN TEXT LIMIT = 6000 CARD MAX TOKENS = 800 REVIEW MAX TOKENS = 4000 SUGGESTION STATUSES = "proposed", "accepted", "rejected", "ignored" EXTRA PRUNE = {".memory", "dist", "out", "release", "build", "coverage", "htmlcov"} ⋮---- CARD PROMPT = """You are cataloguing one project-plan document for a cross-project idea index. ⋮---- REVIEW PROMPT = """You are reviewing EVERY project plan one person has scattered across their machine, indexed below as one-line cards, alongside the codebases they already have mapped in Atlas. ⋮---- class ScoutError RuntimeError ⋮---- def read json path: Path, default ⋮---- def load cards - dict ⋮---- def load suggestions - d… Evidence: `cms/scout.py` - **1 .d.ts-heavy directories — TypeScript declaration files are compiler output** (source_file): HARD PRUNE = {"node modules", ".git", ".hg", ".svn", "venv", ".venv", "env", ⋮---- GENERATED NAMES = {"generated", " generated ", "vendor", "third party", "third-party"} LARGE DATA BYTES = 200 000 DATA EXTS = {"json", "txt", "csv", "tsv", "xml"} ⋮---- PROJECT MANIFESTS = {"package.json", "pyproject.toml", "setup.py", "go.mod", EMBEDDED MIN FILES = 5 ⋮---- def mkspec lines: list str - pathspec.PathSpec ⋮---- def read lines path: Path - list str ⋮---- def recommend root: Path, included: list str - list dict ⋮---- recs: list dict = ⋮---- by dir: dict str, list str = defaultdict list ⋮---- 1 .d.ts-heavy directories — TypeScript declaration files are compiler output ⋮---- dts = f for f in files… Evidence: `cms/sources.py` - **Tree Export** (source_file): def nest records: list FileRecord - dict ⋮---- tree: dict = {"dirs": {}, "files": } ⋮---- parts = rec.rel path.split "/" node = tree ⋮---- node = node "dirs" .setdefault part, {"dirs": {}, "files": } ⋮---- def fmt size size: int - str ⋮---- def render lines node: dict, indent: str - list str ⋮---- lines: list str = dirs = sorted node "dirs" .items files = sorted node "files" , key=lambda r: r.rel path entries: list tuple str, object = name, sub for name, sub in dirs ⋮---- last = i == len entries - 1 branch = "└── " if last else "├── " cont = " " if last else "│ " ⋮---- rec: FileRecord = item type: ignore assignment meta = f" {rec.line count} lines · { fmt size rec.size bytes } · {rec.langua… Evidence: `cms/tree_export.py` - **A build done with the mock provider never ran LLM feature discovery** (source_file): @dataclass class UpdateStats ⋮---- files: int = 0 changed: list str = None summarized: int = 0 features: int = 0 git files: int = 0 ⋮---- def post init self ⋮---- def carry over old: nx.DiGraph, new: nx.DiGraph, upgrade mock: bool = False - set str ⋮---- changed: set str = set ⋮---- path = attrs "path" ⋮---- old attrs = old.nodes node id stale mock = ⋮---- cache: dict str, tuple str, str = {} ⋮---- member paths = { ⋮---- def prior discovered old: nx.DiGraph - list ⋮---- root = root.resolve memory dir = root / config.MEMORY DIR NAME graph path = memory dir / "graph.json" old: nx.DiGraph None = None ⋮---- old = CodebaseMemory.load graph path .graph ⋮---- stats = UpdateStats records = scan roo… Evidence: `cms/update.py` ## Rules the Host AI Must Follow - **Treat this asset as pre-work context, not a runtime environment.**: The AI Context Pack contains only an evidence-backed understanding of the project, not the project's executable state. Evidence: `README.md`, `docs/ATLAS_OPERATIONS.md`, `SKILL.md` - **When answering the user, distinguish what can be previewed from what can only be verified after install.**: The consumer value of the pre-install experience comes from reducing bad installs and misjudgments, not from pretending to be a real run. Evidence: `README.md`, `docs/ATLAS_OPERATIONS.md`, `SKILL.md` ## Questions the User Should Answer First - Which host AI or local environment do you plan to use it in? - Do you just want to experience the workflow first, or are you ready to actually install? - What matters most to you: install cost, output quality, or conflicts with your existing rules? ## Acceptance Checks - Every capability claim can be traced back to a file path in evidence_refs. - AI_CONTEXT_PACK.md does not package previews as a real run. - The user can understand who it fits, what it can do, how to start, and the risk boundaries within 3 minutes. --- ## Doramagic Context Augmentation The following sections strengthen the repository context for a host AI. Human Manual data is a reading route, and pitfall notes become operating constraints. ## Human Manual Outline Usage rule: this is only a reading route and salience signal, not factual authority. Concrete claims must still return to repo evidence or Claim Graph. Host AI hard rules: - Do not treat page titles, section order, summaries, or importance values as factual project evidence. - When explaining the Human Manual outline, state that it is only a reading route or salience signal. - Capability, installation, compatibility, runtime state, and risk claims must cite repo evidence, source paths, or Claim Graph. - **Project Introduction and System Architecture**: importance `high` - source_paths: README.md, codebase_memory_system_design_spec.md, docs/ATLAS_OPERATIONS.md, pyproject.toml, cms/__init__.py - **Memory Engine, Knowledge Graph and Data Pipeline**: importance `high` - source_paths: cms/scanner.py, cms/graph_builder.py, cms/semantic_state.py, cms/summarizer.py, cms/features.py - **AI Integration, Verification and Hermes Sentinel Quality Gate**: importance `high` - source_paths: cms/providers.py, cms/review.py, cms/suggest.py, cms/verify.py, cms/align.py - **Agent Interfaces, UI Viewer and Discovery Layer**: importance `high` - source_paths: cms/mcp.py, cms/ui.py, cms/ui_assets/index.html, cms/ui_assets/constellation.html, cms/ui_assets/sentinel.html ## Repo Inspection Evidence - repo_clone_verified: true - repo_inspection_verified: true - repo_commit: `f292945f621391f3e92826840b891676b04e734a` - inspected_files: `README.md`, `pyproject.toml`, `docs/ATLAS_OPERATIONS.md`, `docs/AUDIT_REMEDIATION_2026-07-12.md`, `docs/HERMES_SENTINEL.md`, `docs/HUMAN_VIEW.md`, `docs/Resolution-Human-View-feature.md`, `docs/feature_ledger.json` Host AI hard rules: - Without repo_clone_verified=true, do not claim that the source code has been read. - Without repo_inspection_verified=true, do not write README, docs, or package-file conclusions as facts. - Without quick_start_verified=true, do not claim that the Quick Start path has run successfully. ## Doramagic Pitfall Constraints These rules come from Doramagic discovery, validation, or compilation findings. The host AI must treat them as operating constraints, not background notes. ### Constraint 1: Capability evidence risk requires verification - Trigger: README/documentation is current enough for a first validation pass. - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/mrt150683-lgtm/atlas-cms - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 2: Security or permission risk requires verification - Trigger: no_demo - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/mrt150683-lgtm/atlas-cms - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 3: Security or permission risk requires verification - Trigger: no_demo - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/mrt150683-lgtm/atlas-cms - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 4: Maintenance risk requires verification - Trigger: issue_or_pr_quality=unknown。 - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/mrt150683-lgtm/atlas-cms - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 5: Maintenance risk requires verification - Trigger: release_recency=unknown。 - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/mrt150683-lgtm/atlas-cms - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.