anaxigraph 0.1.0__tar.gz

anaxigraph-0.1.0/.anaxigraph.yml

@@ -0,0 +1,80 @@
+project:
+  name: AnaxiGraph
+
+architecture:
+  policy: docs/coding-patterns.md
+  protected_paths:
+    - src/anaxigraph/storage.py
+    - src/anaxigraph/mcp_server.py
+  rules:
+    - id: module-size
+      type: max_module_loc
+      severity: warning
+      max: 500
+      paths: [src/**]
+    - id: function-size
+      type: max_function_lines
+      severity: info
+      max: 40
+      paths: [src/**]
+    - id: symbol-complexity
+      type: max_symbol_complexity
+      severity: warning
+      max: 15
+    - id: fan-out
+      type: max_fan_out
+      severity: warning
+      max: 15
+    - id: dependency-cycles
+      type: no_cycles
+      severity: error
+
+groups:
+  extraction:
+    paths:
+      - src/anaxigraph/analyzers/**
+      - src/anaxigraph/languages.py
+      - src/anaxigraph/scanner.py
+  intelligence:
+    paths:
+      - src/anaxigraph/architecture.py
+      - src/anaxigraph/coverage.py
+      - src/anaxigraph/agent.py
+      - src/anaxigraph/semantic.py
+      - src/anaxigraph/semantic_*.py
+      - src/anaxigraph/understanding.py
+  persistence:
+    paths: [src/anaxigraph/storage.py]
+  interfaces:
+    paths:
+      - src/anaxigraph/api.py
+      - src/anaxigraph/mcp_server.py
+      - src/anaxigraph/cli.py
+      - src/anaxigraph/dashboard/**
+  tests:
+    paths: [tests/**]
+  documentation:
+    paths:
+      - docs/**
+      - '*.md'
+
+agent:
+  context_limit: 25
+  neighbor_depth: 2
+  payload_limit_bytes: 20000
+  protected_paths:
+    - src/anaxigraph/storage.py
+    - src/anaxigraph/mcp_server.py
+
+coverage:
+  files: [coverage.xml]
+
+# Semantic understanding is opt-in because it sends eligible source and graph context to the
+# configured model. See docs/onboarding.md before enabling it.
+semantic:
+  enabled: false
+  provider: agent
+  refresh: manual
+  max_jobs_per_run: 100
+  max_parallel_jobs: 1
+  agent_lease_seconds: 1800

anaxigraph-0.1.0/.dockerignore

@@ -0,0 +1,16 @@
+.anaxigraph
+.git
+.pytest_cache
+.ruff_cache
+.venv
+node_modules
+test-results
+playwright-report
+__pycache__
+build
+coverage.xml
+dist
+*.db
+*.db-shm
+*.db-wal
+*.egg-info

anaxigraph-0.1.0/.env.example

@@ -0,0 +1,25 @@
+# The sibling MaxOS checkout works without creating a .env file.
+# Change this when the target repository lives elsewhere.
+ANAXIGRAPH_REPOSITORY=../maxos_agent
+
+# Parent directory containing every repository you want the container to see.
+# It is mounted read-only at /repositories; only registry entries are scannable.
+ANAXIGRAPH_REPOSITORIES_ROOT=..
+
+# Copy repositories.example.yml to repositories.yml, add your repos, then set this.
+ANAXIGRAPH_REGISTRY=./repositories.example.yml
+
+# Dashboard/API port published only on the local machine by default.
+ANAXIGRAPH_BIND_ADDRESS=127.0.0.1
+ANAXIGRAPH_PORT=8765
+
+# Optional continuous refresh interval used by the `watch` Compose profile.
+ANAXIGRAPH_WATCH_INTERVAL=10
+
+# Optional model-backed module understanding. Credentials stay in the environment, never in the
+# repository policy. Leave both blank when semantic.enabled is false.
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+
+# MaxOS's default Compose network. Override this if its project name changes.
+MAXOS_DOCKER_NETWORK=maxos_agent_default

anaxigraph-0.1.0/Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.12-slim
+
+LABEL org.opencontainers.image.source="https://github.com/hcekne/anaxigraph" \
+      org.opencontainers.image.description="Temporal architecture intelligence for software repositories" \
+      org.opencontainers.image.licenses="Apache-2.0"
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_ROOT_USER_ACTION=ignore
+
+WORKDIR /app
+RUN apt-get update \
+    && DEBIAN_FRONTEND=noninteractive apt-get install --yes --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+COPY pyproject.toml README.md MANIFEST.in LICENSE /app/
+COPY src /app/src
+RUN pip install --no-cache-dir .
+
+RUN useradd --create-home --uid 10001 anaxigraph \
+    && mkdir -p /state \
+    && chown anaxigraph:anaxigraph /state
+USER anaxigraph
+
+EXPOSE 8765
+ENTRYPOINT ["anaxigraph"]
+CMD ["serve", "--host", "0.0.0.0", "--port", "8765"]

anaxigraph-0.1.0/LICENSE

@@ -0,0 +1,134 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined
+by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is
+granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are
+controlled by, or are under common control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this
+License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to
+software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a
+Source form, including but not limited to compiled object code, generated documentation, and
+conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under
+the License, as indicated by a copyright notice that is included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or
+derived from) the Work and for which the editorial revisions, annotations, elaborations, or other
+modifications represent, as a whole, an original work of authorship. For the purposes of this
+License, Derivative Works shall not include works that remain separable from, or merely link (or
+bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and
+any modifications or additions to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or
+Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this
+definition, "submitted" means any form of electronic, verbal, or written communication sent to the
+Licensor or its representatives, including but not limited to communication on electronic mailing
+lists, source code control systems, and issue tracking systems that are managed by, or on behalf of,
+the Licensor for the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a
+Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a
+Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each
+Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display,
+publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object
+form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor
+hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made, use, offer to sell, sell,
+import, and otherwise transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by
+combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If
+You institute patent litigation against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses granted to You under this License for
+that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form, provided that You meet
+the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You changed the
+files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright,
+patent, trademark, and attribution notices from the Source form of the Work, excluding those notices
+that do not pertain to any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative
+Works that You distribute must include a readable copy of the attribution notices contained within
+such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works,
+in at least one of the following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along with the Derivative
+Works; or, within a display generated by the Derivative Works, if and wherever such third-party
+notices normally appear. The contents of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution notices within Derivative Works that You
+distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such
+additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or
+different license terms and conditions for use, reproduction, or distribution of Your
+modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and
+distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution
+intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms
+and conditions of this License, without any additional terms or conditions. Notwithstanding the
+above, nothing herein shall supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service
+marks, or product names of the Licensor, except as required for reasonable and customary use in
+describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor
+provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any
+warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
+PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing
+the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including
+negligence), contract, or otherwise, unless required by applicable law (such as deliberate and
+grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages,
+including any direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the Work (including but
+not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any
+and all other commercial damages or losses), even if such Contributor has been advised of the
+possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works
+thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this License. However, in accepting
+such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor
+harmless for any liability incurred by, or claims asserted against, such Contributor by reason of
+your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

anaxigraph-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include .anaxigraph.yml
+include .dockerignore
+include .env.example
+include Dockerfile
+include LICENSE
+include compose.maxos.yml
+include compose.yml
+include repositories.example.yml
+include repo_instructions.md
+recursive-include docs *.md
+recursive-include examples *.yml
+recursive-include src/anaxigraph/dashboard *.html *.css *.js *.svg

anaxigraph-0.1.0/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: anaxigraph
+Version: 0.1.0
+Summary: A temporal architecture and intelligence layer for software repositories
+Author: AnaxiGraph contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/hcekne/anaxigraph
+Project-URL: Repository, https://github.com/hcekne/anaxigraph
+Keywords: architecture,static-analysis,knowledge-graph,mcp,repository-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: mcp<2,>=1.28
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: uvicorn<1,>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx<1,>=0.27; extra == "dev"
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: pytest-cov<7,>=5; extra == "dev"
+Requires-Dist: ruff<1,>=0.9; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="src/anaxigraph/dashboard/favicon.svg" width="112" alt="AnaxiGraph logo" />
+</p>
+
+<h1 align="center">AnaxiGraph</h1>
+
+<p align="center">
+  <strong>Keep AI-accelerated codebases coherent as they grow.</strong><br />
+  See the architecture, control entropy, and give coding agents grounded context.
+</p>
+
+<p align="center">
+  <a href="https://github.com/hcekne/anaxigraph/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/hcekne/anaxigraph/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="LICENSE"><img alt="Apache 2.0 license" src="https://img.shields.io/badge/license-Apache--2.0-167a96" /></a>
+  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-315f9f" />
+  <img alt="MCP Streamable HTTP" src="https://img.shields.io/badge/MCP-Streamable_HTTP-7652a4" />
+</p>
+
+<p align="center">
+  <a href="docs/onboarding.md">Get started</a> ·
+  <a href="docs/docker.md">Docker guide</a> ·
+  <a href="CONTRIBUTING.md">Contribute</a>
+</p>
+
+AI makes it easy to add code faster than a team can understand the architecture absorbing it.
+Hidden coupling, duplicated behavior, inconsistent abstractions, and one-off agent changes can
+quietly accumulate into spaghetti code.
+
+AnaxiGraph creates an architectural feedback loop for that problem. It turns a repository and its
+Git history into a living, explorable system map, helping people and coding agents understand how
+the code fits together before they change it. The goal is not architecture-by-score; it is to make
+important trade-offs visible, evidence-backed, and reviewable while there is still time to act.
+
+| | What you get |
+|---|---|
+| 🧹 **Control entropy** | Catch growing modules, dependency cycles, boundary erosion, and repeated responsibilities before they harden into spaghetti code. |
+| 🏛️ **Build for change** | Review whether boundaries, patterns, and abstraction candidates fit the codebase you have and the system you are building toward. |
+| 🕸️ **Graph understanding** | Move from a bird's-eye architecture map to the dependencies, history, and evidence behind an individual module. |
+| 🕰️ **Repository biography** | Replay how the system grew across real Git history instead of seeing only today's tree. |
+| 🧭 **Auditability** | Trace findings and interpretations back to files, relationships, commits, and snapshots. |
+| 🤖 **Safer AI coding** | Give Codex a small, evidence-backed work envelope so agent changes respect the wider architecture. |
+
+Under the hood, AnaxiGraph is a standalone temporal architecture observatory. It scans source and
+Git history without modifying the target, persists a versioned dependency graph, evaluates
+architecture signals, renders an interactive dashboard, and serves bounded context and impact
+analysis to coding agents.
+
+The dashboard includes a filterable Modules ledger for purpose, architecture placement, size,
+complexity, coupling, Git activity, imported coverage, findings, and review attention. Graph
+regions scale with their module populations so dense areas receive proportionally more space.
+
+### Three surfaces, one index
+
+- **🔭 AnaxiGraph** is the dashboard, analysis engine, and overall project.
+- **🗂️ AnaxiIndex** is the persistent SQLite knowledge store for repositories, modules, symbols,
+  relationships, intent, findings, and history.
+- **🔌 AnaxiMCP** exposes that knowledge to Codex and other coding agents over MCP.
+
+The analysis engine is Python-first and supports mixed repositories containing Python,
+TypeScript, JavaScript, JSX, CSS, configuration, and documentation.
+
+### Deterministic facts + real module understanding
+
+AnaxiGraph has two separate AI-facing paths that reinforce one another:
+
+```text
+source + Git ── deterministic scan/hashes ──→ versioned graph
+                                                   │ changed modules only
+                                                   ▼
+                                  semantic work queue in AnaxiIndex
+                                      │                        │
+                            connected coding agent      optional model worker
+                                      └──────────┬─────────────┘
+                                                 ▼
+                                versioned semantic dossiers
+```
+
+The first opt-in semantic bootstrap reads every eligible first-party module and records its
+purpose, contracts, architecture role, related responsibilities, pattern opportunities,
+placement guidance, risks, and provenance. It then synthesizes subsystem and repository context.
+Later scans compare structural, interface, relationship, prompt, model, and intent fingerprints,
+so unchanged source is reused rather than paid for again. Parser facts and model interpretations
+remain separate throughout.
+
+## 🚀 Get running in five minutes
+
+AnaxiGraph normally runs as a Docker sidecar beside the repository you are coding in. From that
+repository, run these commands in a **normal terminal**:
+
+```bash
+cd /path/to/your/repository
+uvx --from git+https://github.com/hcekne/anaxigraph anaxigraph init .
+docker compose -f compose.anaxigraph.yml up -d
+```
+
+The initializer writes `.anaxigraph.yml` and `compose.anaxigraph.yml` without replacing existing
+files. The Compose service mounts the repository read-only, persists AnaxiIndex in a named volume,
+scans the current tree, and imports representative graph frames from the initial Git commit
+through HEAD.
+
+Open <http://127.0.0.1:8765> and follow the four-step dashboard tour.
+
+## 🤖 Connect Codex
+
+Run the following in a shell on the machine where Codex itself runs. It can be run from any
+directory:
+
+```bash
+codex mcp add anaxigraph --url http://127.0.0.1:8765/mcp
+codex mcp list
+```
+
+By default, `codex mcp add` stores the connection in `~/.codex/config.toml`. Future Codex CLI and
+IDE sessions on that same host can then use AnaxiMCP from any coding repository. Start a new Codex
+session in the project you want to edit:
+
+```bash
+cd /path/to/your/repository
+codex
+```
+
+If you want the connection available only inside one trusted repository, add it to that
+repository's `.codex/config.toml` instead:
+
+```toml
+[mcp_servers.anaxigraph]
+url = "http://127.0.0.1:8765/mcp"
+```
+
+### Remote Linux server + local browser
+
+When AnaxiGraph and Codex run on a remote Linux server while you view the dashboard from another
+computer, the Codex-to-AnaxiMCP route is direct:
+
+```text
+Codex on server ── http://127.0.0.1:8765/mcp ──→ AnaxiMCP container
+Local browser   ── SSH port forward ───────────→ dashboard on :8765
+```
+
+The SSH tunnel is only needed by the browser. Codex on the server does not go through your local
+computer or the tunnel; it reaches the published container port on its own host. A server session
+looks like this:
+
+```bash
+# Run on the Linux server where Codex runs
+curl http://127.0.0.1:8765/healthz
+codex mcp add anaxigraph --url http://127.0.0.1:8765/mcp
+codex mcp list
+cd /path/to/your/repository
+codex
+```
+
+If Codex runs on your local computer instead, the forwarded URL works while the SSH tunnel is
+active. If Codex itself runs in another container on the same Docker network, use
+`http://anaxigraph:8765/mcp` instead of `127.0.0.1`.
+
+Other MCP clients use the same endpoint. See the complete [onboarding guide](docs/onboarding.md)
+for the human-to-agent workflow, optional coverage, history, custom ports, updates, and reset
+behavior, and the official [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp)
+for Codex configuration details.
+
+### Build the semantic baseline with your coding agent (optional)
+
+The recommended Docker path needs no LLM key inside AnaxiGraph. Enable agent-funded semantics in
+`.anaxigraph.yml`:
+
+```yaml
+semantic:
+  enabled: true
+  provider: agent
+  refresh: manual
+  max_parallel_jobs: 1
+  agent_lease_seconds: 1800
+```
+
+Refresh the scan or choose **Prepare semantic work** in the dashboard. Then ask the coding agent
+that is already connected to AnaxiMCP and running in the target repository:
+
+> Use AnaxiGraph to build or resume the semantic baseline for this repository. Call
+> `ANAXIGRAPH_SEMANTIC_SCHEMA` once, then repeat `ANAXIGRAPH_SEMANTIC_WORK`, fetch every requested
+> evidence page, analyze the module or scope using your own model context, and call
+> `ANAXIGRAPH_SEMANTIC_SUBMIT`. Continue until WORK returns `complete`. Do not edit source while
+> performing this mapping task.
+
+AnaxiGraph chooses only stale work, supplies source plus deterministic graph/Git evidence, leases
+each job, validates the returned dossier, and writes it to AnaxiIndex. The coding agent supplies
+the reasoning and uses its own token allowance. The repository mount remains read-only, and the
+queue can resume in another agent session if the first session stops.
+
+An in-container hosted worker remains available as an alternative for unattended schedules:
+
+```yaml
+semantic:
+  enabled: true
+  provider: openai       # or anthropic
+  model: your-model
+  refresh: periodic
+```
+
+```bash
+export OPENAI_API_KEY="..."       # use ANTHROPIC_API_KEY for provider: anthropic
+docker compose -f compose.anaxigraph.yml --profile ai up -d
+docker compose -f compose.anaxigraph.yml logs -f anaxigraph-semantic
+```
+
+For a local installation, `provider: codex` and `provider: claude` run those authenticated CLIs as
+workers. The [semantic onboarding guide](docs/onboarding.md#build-the-ai-understanding-baseline)
+explains the agent-funded loop, hosted workers, privacy controls, incremental invalidation, and
+scheduling.
+
+## 🔄 Keep it current
+
+Follow startup or scanning with:
+
+```bash
+docker compose -f compose.anaxigraph.yml logs -f anaxigraph
+```
+
+To refresh automatically while you code, enable the optional watcher:
+
+```bash
+docker compose -f compose.anaxigraph.yml --profile watch up -d
+```
+
+## 🗺️ Shared multi-repository service
+
+The repository also contains an operator setup for one dashboard across several allowlisted
+read-only mounts. This is useful for a team installation or for switching projects without
+running several ports:
+
+```bash
+git clone https://github.com/hcekne/anaxigraph.git
+cd anaxigraph
+cp .env.example .env
+cp repositories.example.yml repositories.yml
+# Edit the host mounts and registry, then:
+docker compose up --build -d
+```
+
+The browser cannot ask the server to browse arbitrary host paths. See
+[Docker operation](docs/docker.md) and [MaxOS integration](docs/maxos-agent.md).
+
+## 💻 Local CLI
+
+```bash
+uv tool install -e .
+anaxigraph init /path/to/repository --no-compose
+anaxigraph scan /path/to/repository
+anaxigraph serve --repository /path/to/repository --scan-on-start --open
+```
+
+AnaxiIndex is stored outside the target at
+`${XDG_STATE_HOME:-~/.local/state}/anaxigraph/anaxi-index.db`. Override it with `--db` or
+`ANAXIGRAPH_DB`.
+
+Useful commands:
+
+```bash
+anaxigraph update /path/to/repository
+anaxigraph understand /path/to/repository
+anaxigraph semantic-status /path/to/repository
+anaxigraph history /path/to/repository --limit 64
+anaxigraph review /path/to/repository
+anaxigraph scope /path/to/repository --goal "Add saved prompts to Workbench"
+anaxigraph impact /path/to/repository --target backend/app/services/chat.py
+anaxigraph watch /path/to/repository
+anaxigraph mcp --repository /path/to/repository --port 8765
+```
+
+The `serve` and `mcp` commands both expose the dashboard and JSON API at
+`http://127.0.0.1:8765`, with Streamable HTTP MCP at `http://127.0.0.1:8765/mcp`. See
+[`docs/maxos-agent.md`](docs/maxos-agent.md) for the ready-to-run MaxOS integration.
+
+## 🧠 What is persisted
+
+- repositories, commit/working-tree snapshots, artifacts, and artifact versions
+- source symbols and deterministic import/call relationships with evidence
+- raw and language-aware structural hashes for incremental scans
+- declared and inferred architecture groups
+- metrics, coverage measurements, Git change history, and temporal trends
+- architecture findings with stable identity and lifecycle state
+- durable intrinsic, contextual, subsystem, and repository dossiers with provider/model/prompt
+  plus coding-agent executor provenance, resumable work state, fingerprints, token usage, and
+  cost estimates
+
+The target repository only needs an optional `.anaxigraph.yml`; analysis state remains external.
+
+## 🛠️ Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+```
+
+The product brief and requirement source is [`repo_instructions.md`](repo_instructions.md).
+Contributions are welcome; see [`CONTRIBUTING.md`](CONTRIBUTING.md).