AutoGineer
Generated banner for MirrorArc
Generated logo for MirrorArc

MirrorArc

LLM wiki kit

First committed by cz1993

Published in cz1993/MirrorArc. Publisher page

97 GitHub stars

What it is

Local-first, governed documentation for humans and AI agents—mirror Office, PDF, and GitHub sources into linked Markdown knowledge workspaces.
— the description by cz1993

Summary from the brain’s metadata

Local-first, governed documentation for humans and AI agents—mirror Office, PDF, and GitHub sources into linked Markdown knowledge workspaces. Preserve sources. Minimize derived documents. Generate knowledge views when they are needed.

How it works

Memory model: LLM wiki

AutoGineer overview, from the brain’s own files

Memory model: LLM wiki. Folders: .github (agent config, 3 files); docs (docs, 33 files); examples (examples, 139 files); scripts (scripts, 11 files); src (source code, 126 files); template (templates, 54 files); tests (tests, 57 files). The agent reads README.md, docs/PRODUCT.md. The agent writes CHANGELOG.md.

Folders
FolderRoleFiles
.githubagent-config3
docsdocs33
examplesexamples139
scriptsscripts11
srcsource-code126
templatetemplates54
teststests57
.githooksfolder1
clifolder1

The agent reads

The agent writes

Requirements

Apps: Obsidian

Runtimes: Python >=3.11

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. This brain runs code automatically: 2 scripts. Review .githooks/pre-commit, scripts/init.sh before opening the folder in Claude Code. No step below turns a hook on for you.

    • .githooks/pre-commit: runs on git pre-commit
    • scripts/init.sh: sh scripts/init.sh

  2. Clone the repository at the commit AutoGineer scanned:

    git clone https://github.com/cz1993/MirrorArc.git && cd MirrorArc && git checkout 1df13ebf6efb33018e29a1ea365cde0cf53d41c7

  3. Point Claude Code at AGENTS.md: it does not read that file on its own.

  4. cd MirrorArc && claude

  5. AutoGineer scanned these files at commit 1df13eb.

  6. Not scanned by AutoGineerThe author’s README also describes installing it from a clone of its repository. Read its install section: AutoGineer did not scan that path. https://github.com/cz1993/MirrorArc/blob/1df13ebf6efb33018e29a1ea365cde0cf53d41c7/README.md#quick-start

  7. First committed by cz1993. Published in cz1993/MirrorArc. Licence: GNU Affero General Public License v3.0 only.

Usage

From the brain’s own files

  • Create a vault without cloning MirrorArc itself.
  • The installable command requires Python 3.11+; uvx and pipx run will build an isolated environment when they can find a compatible Python.
  • Before the package is published to PyPI, use the Git URL:
  • Once MirrorArc is published to PyPI, the equivalent short forms are uvx mirrorarc init --profile data-product ~/my-data-product and pipx run mirrorarc init --profile data-product ~/my-data-product.
  • For repeated local use, install the console command once:
  • Then open the vault in Obsidian if you want a human UI, point your agent at it (CLAUDE.md routes all agents to _meta/agent-rules.md), and run the installed command from any folder:
  • Run sandbox from a duplicated pilot vault, not the original document folder.
  • It is read-only and checks copy-boundary, mirror isolation, manifest/recovery readiness, and basic backup posture without printing source paths or document text.

Documentation by cz1993

MirrorArc

Image: Python 3.11+ Image: License: AGPL-3.0 Image: Status: technical alpha

Preserve sources. Minimize derived documents. Generate knowledge views when they are needed.

Open the live Ontario Grid demo portal →

MirrorArc is an open-source, local-first Python toolkit that turns changing Office files, PDFs, GitHub repositories, datasets, and Markdown into a governed knowledge-projection system. It keeps original records authoritative, creates deterministic Markdown projections for opaque sources, maintains source-backed relationships, and renders human or agent context without adding a vector database or an AI-generated wiki.

Image: MirrorArc beginner landing page showing the Ontario Electricity evidence tutorial

Why MirrorArc exists

Generative AI made documentation fast and cheap to create. It did not make a growing collection of summaries, entity pages, hubs, and agent notes cheap to verify or maintain. MirrorArc treats every durable derivative as a liability that must justify its existence; the information and knowledge carried by the sources remain the asset.

The product principle is:

Preserve authoritative records. Treat every durable derivative as a maintenance liability. Generate views instead of accumulating documents.

Common failureMirrorArc's response
Office files, PDFs, spreadsheets, repos, and Markdown stay isolated.L1 specular projections: opaque sources receive stable, source-addressed Markdown read models while originals remain authoritative.
AI documentation creates more files than anyone can govern.Anti-proliferation by architecture: relationships are data and synthesis is a view, not another note by default.
Cross-document meaning is hidden or asserted without evidence.Relationship and provenance ledger: typed connections carry evidence anchors, hashes, generation method, confidence, and review state.
Human readers need interpretation rather than raw extraction.L2 knowledge views: many sources produce a few purpose- and audience-specific reading surfaces that are ephemeral unless pinned or reviewed.
Source changes leave summaries and agent context stale.Dependency-aware refresh: changed sources invalidate only affected projections, relationships, views, reviews, and context.
Sensitive or stale material enters an opaque index.Visible governance: authority, licensing, PII boundaries, lifecycle, freshness, and publication gates remain explicit.

See the connected evidence

The self-contained Catalog Explorer provides a relationship map, a provenance and lifecycle inspector, and a rendered document view. When a governed repository is selected, an optional Code view adds revision-bound source evidence, call paths, impact, and affected-test candidates. The catalog panel is resizable, long filenames wrap instead of disappearing, and INDEX.md is pinned as the beginner guide.

Image: MirrorArc relationship map connecting an original Word document and its generated Markdown mirror

Image: MirrorArc metadata view showing provenance, authority, lifecycle state, and source-to-mirror relationships

Flagship demo: Ontario electricity evidence workspace

examples/ontario-electricity-evidence-vault/ is the flagship clean-room data-product example, built from OGL Ontario data, metadata-only public references, independently authored Word/Excel artifacts, and a synthetic repository fixture. The current snapshot demonstrates the implemented L1, lifecycle, catalog, and portal foundation. Its large hand-authored Markdown layer predates the knowledge-projection architecture and is now a migration fixture rather than the target output.

The local implementation supports source-addressed L1, evidence relationships, reviewed L2 views, dynamic/frozen context, and dependency invalidation. The checked-in example remains deliberately small. Historical stress tests are recorded separately; current batch proof is documented in the Trustworthy Context handoff when available.

The committed snapshot is an independently assembled educational corpus, not live grid data, forecasting, alerts, or an affiliated Ontario energy product.

Launch the hosted demo and start with the pinned INDEX.md five-minute tour. GitHub Pages rebuilds this content-enabled portal only from the provenance-documented public example and blocks deployment unless both the repository-wide provenance/no-data gate and the generated-artifact scan pass alongside vault lint.

The hosted project is progressively discoverable: the project overview identifies MirrorArc's purpose, differentiators, installation path, licence, and canonical GitHub source in semantic HTML. The demo's initial HTML contains the rendered beginner tour, while documents/ provides one semantic, no-JavaScript page per public record. Search and agent discovery surfaces include sitemap.xml, robots.txt, llms.txt, raw public Markdown, and a metadata-only catalog.json.

Try the demo locally

git clone https://github.com/cz1993/MirrorArc.git
cd MirrorArc
python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

mirrorarc --root examples/ontario-electricity-evidence-vault sync
mirrorarc --root examples/ontario-electricity-evidence-vault code doctor
# If Ready, optionally analyze the synthetic repository fixture:
mirrorarc --root examples/ontario-electricity-evidence-vault code analyze --repo repo_252e1077b0082592ba3d --symbol demand_change
mirrorarc --root examples/ontario-electricity-evidence-vault catalog --html --include-content
python -m http.server 8000 --directory examples/ontario-electricity-evidence-vault

Open http://127.0.0.1:8000/CATALOG.html. Start with the pinned INDEX.md, then follow the five-minute tour. The --include-content output embeds bounded Markdown bodies and must remain local for private or proprietary vaults. The hosted MirrorArc demo is a narrow exception: it is built only from the public example corpus and scanned again before every deployment.

Choose a task and export its evidence

From a synced vault, choose a task, inspect what was selected and omitted, then freeze evidence:

mirrorarc --root <vault> context build --lens orientation --mode metadata --query "inspection interval" --json
mirrorarc --root <vault> context build --lens orientation --query "inspection interval" --name inspection-review
# Use the definition ID printed above:
mirrorarc --root <vault> context resolve <definition-id> --json
mirrorarc --root <vault> context freeze --definition <definition-id> --task "Explain the inspection interval with citations."
mirrorarc --root <vault> catalog --html

Query retrieval is opt-in: lexical ranking can miss relevant evidence. Inspect source hashes, exact spans, selected/excluded reasons, warnings and omissions before use. Metadata contains references only. Frozen packs include bounded evidence and report exact serialized bytes plus an estimated token count, not a model-independent token guarantee. A tiny budget can fail because instructions and citations alone do not fit. offline_complete is false if selected evidence is missing or truncated; it is never a guarantee that the sources answer your question.

The portable Catalog's selection download stays metadata-only. Its governed-context panel shows saved tasks, copyable commands and frozen status. HTML does not execute those commands. Use --include-content only when intentionally embedding local evidence; protect the resulting file according to its sensitivity. Source changes require refresh, context resolution, and Catalog regeneration. Frozen bytes remain unchanged and status reports staleness.

Review PDF page evidence

The optional PageIndex integration adds physical-page evidence and unreviewed answer candidates to the same governed workflow. Install its separate pinned runtime using the PageIndex setup and review guide, then start with model-free indexing:

mirrorarc --root /absolute/path/to/copied-vault document doctor
# Use a registered PDF source ID from mirrorarc status --json:
mirrorarc --root /absolute/path/to/copied-vault document index --source SOURCE_ID --context frozen --page 2
mirrorarc --root /absolute/path/to/copied-vault catalog --html --include-content

In the Catalog, select the PDF, then Document metadata → PDF page evidence. Optional questions require an approved model/endpoint and explicit per-command consent; indexing alone does not create an answer. Answer review shows frozen cited excerpts, current/stale state and uncertainty. A valid page address does not establish that a claim is supported. The local results separate tested behavior from real-model quality, owner acceptance and release readiness.

How it works

  1. Register authoritative sources without changing them.

  2. Project each opaque source into one stable, machine-owned L1 Markdown read model.

  3. Connect evidence through typed relationships with provenance and review state rather than creating more notes.

  4. Interpret many sources through a small number of purpose-specific L2 knowledge views.

  5. Assemble dynamic or frozen context for a human review or agent task.

  6. Refresh only affected projections and dependants when sources change, with reconciliation and full sync retained for recovery and verification.

The default data-product profile covers sources, contracts, pipelines, analysis, models, outputs, governance, and operations. Additional packaged profiles support business operations, research/learning, software-project documentation, and minimal blank starts.

Inspired by Andrej Karpathy's "LLM wiki" pattern. See docs/positioning.md for the product landscape and boundaries.

Quick start

Create a vault without cloning MirrorArc itself. The installable command requires Python 3.11+; uvx and pipx run will build an isolated environment when they can find a compatible Python. Before the package is published to PyPI, use the Git URL:

uvx --from git+https://github.com/cz1993/MirrorArc.git mirrorarc init --profile data-product ~/my-data-product

# or, with pipx:
pipx run --spec git+https://github.com/cz1993/MirrorArc.git mirrorarc init --profile data-product ~/my-data-product

Once MirrorArc is published to PyPI, the equivalent short forms are uvx mirrorarc init --profile data-product ~/my-data-product and pipx run mirrorarc init --profile data-product ~/my-data-product.

For repeated local use, install the console command once:

uv tool install git+https://github.com/cz1993/MirrorArc.git
mirrorarc --version

# or, with pipx:
pipx install git+https://github.com/cz1993/MirrorArc.git
mirrorarc --version

Then open the vault in Obsidian if you want a human UI, point your agent at it (CLAUDE.md routes all agents to _meta/agent-rules.md), and run the installed command from any folder:

mirrorarc --root ~/my-data-product doctor          # check dependencies and vault structure
mirrorarc --root ~/my-data-product plan            # inspect proposed mirror actions first
mirrorarc --root ~/my-data-product sync            # mirror Office files and configured repos
mirrorarc --root ~/my-data-product status          # review manifest-backed lifecycle state
mirrorarc --root ~/my-data-product sync --json     # machine-readable sync evidence for agents/pilots
mirrorarc --root ~/my-data-product status --json   # machine-readable lifecycle status
mirrorarc --root ~/my-data-product doctor --json   # machine-readable preflight report
mirrorarc --root ~/my-data-product conversion --guide   # read-only conversion spot-check + guide
mirrorarc --root ~/my-data-product conversion --init-results # private quality review scaffold
mirrorarc --root ~/my-data-product conversion --results _meta/conversion-quality-results.yml --require-reviewed # after filling scaffold
mirrorarc --root ~/my-data-product migration       # dry-run report for legacy/unknown folders
mirrorarc --root ~/my-data-product migration --runbook  # legacy folder move protocol
mirrorarc --root ~/my-data-product migration --normalize-frontmatter-domains --worksheet # review domain alias cleanup
mirrorarc --root ~/my-data-product recovery --worksheet # review manifest recovery actions
mirrorarc --root ~/my-data-product sandbox --source-root /path/to/original-documents
mirrorarc --root ~/my-data-product catalog         # generate CATALOG.md inventory gateway
mirrorarc --root ~/my-data-product catalog --html  # generate the interactive CATALOG.html explorer
mirrorarc --root ~/my-data-product catalog --html --include-content # local content-review portal
mirrorarc --root ~/my-data-product code doctor     # optional local repository-analysis readiness
mirrorarc --root ~/my-data-product code analyze --repo <repo-id> # bounded revision evidence
mirrorarc --root ~/my-data-product code status --json # current/stale/failed analysis state
mirrorarc --root ~/my-data-product m365            # Microsoft 365/Copilot handoff readiness
mirrorarc --root ~/my-data-product review --json   # summarize metadata-only human review decisions
mirrorarc --root ~/my-data-product overlap         # calibrate overlap thresholds without note bodies
mirrorarc --root ~/my-data-product pilot           # aggregate pilot evidence, no source content
mirrorarc --root ~/my-data-product pilot --worksheet    # redacted Markdown private-pilot summary
mirrorarc --root ~/my-data-product benchmark            # validate agent-readiness task pack, if present
mirrorarc --root ~/my-data-product benchmark --init-tasks    # create private task scaffold
mirrorarc --root ~/my-data-product benchmark --worksheet     # print private benchmark run sheet
mirrorarc --root ~/my-data-product benchmark --init-results  # create private result scaffold
mirrorarc --root ~/my-data-product benchmark --results _meta/agent-readiness-results.yml --require-prompt-safety # after scoring
# edit tools/repos.yml, then:
mirrorarc --root ~/my-data-product sync           # mirror configured GitHub repos too
mirrorarc --root ~/my-data-product lint           # health check

Run sandbox from a duplicated pilot vault, not the original document folder. It is read-only and checks copy-boundary, mirror isolation, manifest/recovery readiness, and basic backup posture without printing source paths or document text.

Use review after spot-checking mirrors, catalogs, or handoff reports. It appends metadata-only decisions to _meta/review-ledger.jsonl with artifact hashes, so later changes are reported as stale reviews instead of silently preserving old approvals.

The generated CATALOG.html is a self-contained Catalog Explorer. It opens on INDEX.md, offers separate relationship-map, document-metadata, rendered-document, and contextual Code views, preserves explicit original-to-mirror lineage, and keeps local context-pack exports metadata-only. Repository analysis runs before generation; the passive HTML never starts a process or fetches data. The safe default does not embed document bodies. Use catalog --html --include-content only for a local review copy; that opt-in mode embeds bounded Markdown and generated-mirror bodies, so the resulting HTML must be protected like the vault itself. The public GitHub Pages demo is built from the explicitly public, provenance-documented example and passes the no-data gate before deployment. Neither mode requires an application server or creates an evidence index.

Source checkout fallback:

git clone https://github.com/cz1993/MirrorArc.git mirrorarc && cd mirrorarc
python3.11 -m pip install -e .
mirrorarc --version
mirrorarc profile list
mirrorarc init --profile data-product ~/my-data-product
mirrorarc init --profile business-operations ~/my-business-vault
mirrorarc init --profile research-learning ~/my-research-vault
mirrorarc init --profile software-project ~/my-software-vault
mirrorarc init --profile blank ~/my-blank-vault
mirrorarc --root ~/my-data-product profile validate
mirrorarc --root ~/my-data-product profile diff 0.2.0
mirrorarc --root ~/my-data-product profile migrate --plan
mirrorarc --root ~/my-data-product profile migrate --write
mirrorarc --root ~/my-data-product profile views --check
mirrorarc --root ~/my-data-product migrate annotations --plan
mirrorarc --root ~/my-data-product plan

The packaged v1 profiles are data-product (the default), business-operations, research-learning, software-project, and blank. Each initializes from the installable package with profile-owned folders, _meta/profile.yml, generated scaffold docs, and only the templates declared by its contract.

Profile contract details: docs/PROFILE_SCHEMA.md.

Step-by-step: docs/quickstart.md.

Documentation

The whitepaper defines architectural principles; the current Trustworthy Context plan governs this local batch. Earlier implementation plans record historical evidence, not current acceptance.

  • Product contract — audience, workflow, outcomes, and non-goals.

  • Quickstart — demo-first setup and daily workflow.

  • Sync specification — authority, mirroring, manifests, and refresh behavior.

  • Security model — trust boundaries, prompt safety, and local-review rules.

  • Profile schema — configurable domains, note types, folders, and policies.

  • Methodology — L0/L1, relationships, L2, context, review, and promotion discipline.

  • Positioning — where MirrorArc fits relative to LLM wikis, RAG, PKM, and document-management tools.

Status

v0 - technical alpha. Source-preserving L1 mirrors, manifests, lifecycle state, audit logs, journaled changed-file materialization, reconciliation, full recovery sync, profiles, lint/safety guards, the portable catalog, stable projection identities, and the versioned evidence-backed relationship ledger work today.

Dependency invalidation, L2 knowledge views, dynamic/frozen context assembly, and optional revision-bound Repository Intelligence are implemented locally. The current Ontario example is retained as migration and regression evidence; do not interpret its curated Markdown count as the target MirrorArc model. This remains a technical alpha, and local proof is not hosted or production proof.

License

MirrorArc is licensed under the GNU Affero General Public License v3.0 or later for the open core, with a separate commercial license planned for enterprise/closed use and consulting. LICENSE contains the full AGPL-3.0 text; commercial terms and contribution policy still require owner/counsel finalization before accepting outside contributions. See LICENSING.md. "MirrorArc" is a trademark — see TRADEMARK.md.

Credits

The "LLM wiki" pattern (Andrej Karpathy), markitdown (Microsoft), and Obsidian. Interoperates with — rather than competes with — tools like basic-memory and Copilot for Obsidian.

docs/CODE_INTELLIGENCE_EXECUTION_PLAN.md

MirrorArc Repository Intelligence Execution Plan

Status: implemented and locally proven

Date: 2026-08-12

Research inputs:

Execution prompt: prompts/CODE_INTELLIGENCE_EXECUTION_KICKOFF.md

Repository: /Users/cz/workspaces/cz1993/MirrorArc

1. Outcome

Deliver an optional Repository Intelligence capability that lets a normal MirrorArc user:

  1. connect or select a governed source repository;

  2. run one understandable analysis command;

  3. inspect architecture, relevant symbols, call relationships, change impact, affected tests, freshness, and exact source evidence in the Catalog Explorer;

  4. add bounded, source-backed code evidence to a MirrorArc context pack.

The feature must preserve MirrorArc's product identity. It is not a general code-search product and does not replace the existing repository mirror, relationship ledger, lifecycle engine, context assembly, or catalog. It adds a disposable structural read model beneath those governed surfaces.

Success means a new user can reach a useful repository result with one short setup path, one analysis command, and no knowledge of MCP, Cypher, SQLite, ASTs, or provider terminology.

2. Product Decision

First implementation provider

Use CodeGraph as the single optional engine for the first release, through its local CLI and machine-readable commands. It aligns with MirrorArc's no-vector-database direction, exposes symbol/call/impact/affected-test operations, keeps its index in local SQLite, and provides useful references for task-shaped output, freshness warnings, progressive disclosure, and output budgets. The implementation spike starts with the currently researched release, CodeGraph v1.5.0. Pin the version in documentation and product evidence; do not resolve a floating latest release during normal MirrorArc operation.

Use codebase-memory-mcp as a design and benchmarking reference only in this slice. Its index coverage checks, tiered confidence language, explicit root confinement, and one-shot CLI operation are valuable patterns. Do not integrate its vector-backed semantic query, ADR store, daemon, watcher, shared graph artifact, or agent-configuration installer.

Do not build a multi-provider framework in this release. Keep the CodeGraph subprocess boundary small enough to replace later, but do not add provider registries, plugin discovery, abstract factories, or compatibility layers without a second proven provider requirement.

Supported CodeGraph surface

Prefer stable JSON output from:

codegraph status --json
codegraph query ... --json
codegraph callers ... --json
codegraph callees ... --json
codegraph impact ... --json
codegraph affected ... --json
codegraph files ... --json

Do not make correctness depend on parsing human-formatted codegraph explore output. MirrorArc should read any included source span itself from the pinned repository snapshot, then record the path, line range, file hash, repository revision, and truncation state.

Authority boundary

  • The repository and its recorded revision remain L0 authority.

  • The existing repository Markdown mirror remains the L1 reading surface.

  • The CodeGraph database is local, disposable provider cache—not MirrorArc authority.

  • Provider nodes and edges are not bulk-imported into MirrorArc's relationship ledger.

  • Only bounded results selected for a report or context pack become MirrorArc derived artifacts.

  • Heuristic or unresolved provider relationships are visibly labeled and never silently promoted.

  • A commit/tree mismatch makes previous analysis stale; it never remains silently current.

3. User Experience Contract

First-run flow

The intended path is:

mirrorarc --root <vault> code doctor
mirrorarc --root <vault> code analyze --repo <repo-id>
mirrorarc --root <vault> catalog --html

code doctor must give one clear verdict:

  • Ready — provider found, compatible, telemetry disabled, repository resolvable;

  • Setup needed — show one recommended install command and a retry command;

  • Attention — explain the exact version, path, repository, permission, or stale-index problem.

Keep provider installation separate from the Python package. For macOS and Linux, code doctor should recommend the provider's standalone, self-contained installation pinned to the supported version, followed by the retry command. Do not create a Python optional extra for a non-Python runtime, build a downloader, or silently install software. Document the command and let the user choose whether to run it.

The researched starting command is:

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/v1.5.0/install.sh \
  | CODEGRAPH_VERSION=v1.5.0 sh
mirrorarc --root <vault> code doctor

Before publishing that command, the implementation session must verify the script and v1.5.0 checksums in a disposable environment and confirm that this installer only places the standalone CLI; it must not call the separate agent-configuration command.

MirrorArc must invoke ordinary CodeGraph project commands directly. It must not run codegraph install, modify global agent configuration, enable its MCP server, or start a daemon. Set DO_NOT_TRACK=1, CODEGRAPH_TELEMETRY=0, and CODEGRAPH_NO_UPDATE_CHECK=1 for every managed subprocess.

Primary actions

Keep the first-release public CLI to three actions:

  • code doctor — readiness and actionable setup;

  • code analyze --repo <id> — repository overview and current snapshot, with optional --symbol <name>, --base <ref>, or changed-path inputs for focused evidence and candidate affected tests;

  • code status [--repo <id>] — current/stale/failed analysis state.

Human output should be short and action-oriented. Every command also provides --json for the catalog and automation. Provider command names, database paths, and raw payloads belong under a verbose/debug option, not in the default experience.

Catalog Explorer

Add a Code view only when the selected artifact is a repository or repository projection. Its default state should be a readable evidence dashboard, not a force graph:

  • repository revision and freshness;

  • languages, files, and key entry points;

  • the latest inspected symbol or change set;

  • relevant files and exact line anchors;

  • call flow as an ordered list or compact path;

  • impact grouped by direct, transitive, and test candidates;

  • coverage, heuristic, omission, and staleness warnings;

  • “Add code evidence to context” selection action.

Use progressive disclosure. Show the answer and evidence first; place raw provider diagnostics and large relationship lists behind details controls. Empty and error states must say what happened and offer an exact next command. Preserve keyboard access, responsive layout, safe rendering, long-path readability, and the existing metadata-only/content-inclusive boundary.

The Catalog remains a generated, self-contained HTML artifact. Analysis occurs before generation; the browser must not launch local processes, require a server, or become a second database. Its context action may add evidence to the existing client-side selection manifest or show a copyable CLI command; it must not pretend that a passive HTML file created a governed dynamic/frozen pack.

4. Minimal Data Contract

Store current analysis under the existing disposable local boundary, for example:

.mirrorarc/cache/code-intelligence/<repo-id>/<revision>/

The exact path may change, but no provider database or source checkout is committed. Add ignore and no-data coverage if current rules do not already protect this boundary.

One normalized analysis record needs only:

analysis_id
repo_id
configured_repo
resolved_revision
local_tree_hash when applicable
provider_name
provider_version
analysis_kind
request
created_at
freshness_state
files[]: path, hash, language, selected line ranges
symbols[]: stable provider identity, kind, name, qualified name, path, range
relationships[]: source, target, kind, provenance, depth
affected_tests[]
warnings[]
omissions[]

Use deterministic IDs and canonical JSON ordering. Apply existing context file/token/excerpt ceilings. Do not copy an entire repository, provider database, or unbounded provider response into the ledger, a Markdown mirror, the catalog, or a frozen pack.

5. Workstream 0 — Bounded Provider Spike

Build

  • Pin and record the tested CodeGraph version; do not use a floating latest version at runtime.

  • Use an isolated temporary installation or executable, never the global interactive installer.

  • Run init, status --json, query --json, callers --json, callees --json, impact --json, affected --json, and files --json against the existing synthetic repository fixture.

  • Record actual schemas, exit codes, stderr behavior, index paths, offline behavior, and stale-index behavior in focused adapter fixtures or tests.

  • Confirm every managed invocation disables telemetry and update checks.

  • Confirm the pinned standalone install path works in a clean temporary location without invoking codegraph install or writing agent configuration.

Exit

  • The selected version works on Python repositories on the current macOS environment.

  • The commands needed for the MVP have bounded, parseable output.

  • No agent configuration, MCP entry, watcher, daemon, telemetry event, or tracked repository file is created.

  • If these conditions fail, stop the provider integration with exact evidence and a bounded recommendation. Do not start a second-provider implementation in this batch.

6. Workstream 1 — Snapshot and Adapter

Build

  • Add a small stdlib subprocess adapter with explicit timeouts, environment, output ceilings, version checks, error mapping, and JSON validation.

  • Resolve a configured repository to one immutable revision. Reuse the current repository sync identity and cloning/auth rules rather than creating a second connector.

  • For a local dirty repository, record both HEAD and a deterministic local-tree hash; clearly label the analysis local-uncommitted.

  • Keep provider indexes and any temporary checkout under ignored local state. Use locks or atomic publication only where concurrent writes can corrupt that state.

  • Normalize the small data contract above and derive source excerpts directly from the resolved snapshot with path/symlink/boundary validation.

  • Mark analysis stale when the repository revision/tree hash no longer matches.

Exit

  • Re-running the same request against the same snapshot produces the same normalized content apart from declared timestamps/runtime diagnostics.

  • Changing the snapshot invalidates the previous result without rewriting it as current.

  • A provider failure leaves repository mirrors, manifests, and prior valid analysis untouched.

  • No provider-specific schema leaks beyond the adapter module and its fixtures.

7. Workstream 2 — CLI and Governed Context

Build

  • Implement the minimal CLI selected in Section 3 with helpful defaults and --json.

  • Let analyze initialize or incrementally sync the disposable provider index as needed; users should not learn separate provider lifecycle commands.

  • Generate concise repository overview, symbol evidence, and affected-test reports.

  • Register only the bounded analysis artifact and its repository dependency in MirrorArc state.

  • Allow selected code evidence to enter dynamic or frozen context using the existing context budget, citation, hash, sensitivity, omission, and untrusted-content rules.

  • Never treat affected tests as proof that other tests are unnecessary. Label them candidates and keep the repository's normal test gate authoritative.

Exit

  • A first-time user can move from code doctor to a useful result without provider vocabulary.

  • JSON output is stable enough for the Catalog report model.

  • Every displayed or exported excerpt resolves to a path/range/hash at the recorded revision.

  • Context output remains within declared budgets and reports every omission.

8. Workstream 3 — Friendly Catalog UI

Build

  • Extend the shared Python catalog report; do not add inference logic in JavaScript.

  • Add repository-level readiness, freshness, overview, inspection, impact, and warning states.

  • Provide useful empty states and copyable commands when analysis is unavailable or stale.

  • Use compact cards, tables, and ordered paths. Add graph visualization only if usability evidence shows that a particular relationship cannot be understood more clearly as a path or table.

  • Add “Add code evidence to context” as a selection-manifest action or copyable governed-context command using the existing pack interaction and safety language.

  • Keep the HTML portable and metadata-only by default. Content-inclusive mode may include only the bounded code excerpts already selected by the backend.

Exit

  • A new user can identify the repository, its revision, the main result, evidence, warnings, and next action without reading documentation.

  • Desktop and narrow/mobile layouts have no clipped paths, unreachable actions, or horizontal page scrolling.

  • Keyboard users can reach the Code view, evidence rows, details, and context action.

  • The browser performs no local execution, network fetch, or independent relationship inference.

9. Workstream 4 — Deployment, Documentation, and Product Proof

Build

  • Add a short quickstart with the three-command first-run flow and one troubleshooting table.

  • Update the software-project profile guidance without changing the other profiles' normal flow.

  • Document local cache location, deletion/rebuild, privacy, telemetry suppression, supported provider version, and the fact that code results are derived and revision-bound.

  • Add one synthetic repository walkthrough to the existing Ontario example rather than creating a second demo vault.

  • Update README.md, relevant product/security/recovery docs, template copies when applicable, and CHANGELOG.md after behavior exists.

Proportionate validation

Use focused tests while implementing. The intended test budget is:

  • adapter contract/error/staleness tests using small recorded JSON fixtures;

  • one real provider smoke test against the existing synthetic Python repository fixture;

  • CLI tests for ready, setup-needed, success, stale, and provider-failure outcomes;

  • context tests for revision-bound citations, budgets, and omissions;

  • three browser journeys: no analysis, current analysis, and stale/failed analysis, with one narrow viewport pass and keyboard checks folded into those journeys;

  • one final existing repository gate, template-copy check, no-data scan, build, and fresh-wheel smoke test.

Do not add a large language matrix, multiple providers, performance lab, duplicate UI snapshots, or exhaustive permutations in this slice. A test must protect a user-visible promise, authority or privacy boundary, external CLI contract, or regression-prone failure mode.

Final product proof

From a clean temporary Python 3.11 environment and disposable copy of the existing example:

  1. install the built wheel and the documented optional provider path;

  2. run code doctor and receive Ready;

  3. analyze the synthetic repository without separate provider commands;

  4. inspect one known symbol and resolve its cited source lines;

  5. identify affected tests for one controlled change;

  6. build a bounded context pack containing code evidence;

  7. generate and open the Catalog Explorer;

  8. verify the no-analysis, current, and stale/failure UI states;

  9. remove disposable derived state and prove the feature can rebuild;

  10. run the final local repository and no-data gates once.

10. Explicit Non-Goals

  • no vector embeddings or vector database;

  • no bulk AST graph import into MirrorArc's ledger;

  • no second watcher, repository connector, lifecycle authority, portal database, or sync system;

  • no MCP-server requirement for MirrorArc users;

  • no agent/editor configuration mutation;

  • no provider daemon managed by MirrorArc;

  • no committed .codegraph/, .codebase-memory/, provider SQLite, source checkout, or code body;

  • no natural-language-to-Cypher or generic graph-query UI;

  • no 3D graph or graph-first navigation requirement;

  • no multi-provider framework in the first release;

  • no Python optional-extra shim for installing the external provider;

  • no hosted repository analysis service, SaaS, authentication system, or collaboration layer;

  • no autonomous test selection, code modification, ADR creation, or promotion into authority;

  • no new demo vault, large corpus acquisition, or unrelated knowledge-projection redesign.

11. Execution and Stop Rules

  • Preserve the current dirty worktree and build on the existing knowledge-projection baseline.

  • Work in the order above, but collapse modules or commands when that produces a simpler product.

  • Keep one implementation workstream in progress at a time.

  • Run focused checks after each coherent slice and the full existing gate once near completion.

  • Do not pause for ADS, bilateral CLI review, an independent reviewer, a PR, or hosted CI. They are not required for this project/batch.

  • Do not commit, push, publish, deploy, or install globally unless the operator separately authorizes that external or machine-wide action.

  • Stop only for a genuine authority, destructive-data, privacy, licensing, or irreducible product decision. A hard implementation problem is not itself a blocker.

12. Completion Report

The goal is complete when the final product proof passes and the report includes:

  • the shipped user journey and exact commands;

  • files and modules changed;

  • provider/version and deployment method proven;

  • exact focused and final test results;

  • repository revision, code evidence, context, and UI proof;

  • privacy/telemetry/cache behavior verified;

  • remaining limitations stated plainly;

  • final git status and whether anything was committed, pushed, deployed, or published.

13. Completion Evidence

Repository Intelligence is implemented as an optional local workflow with the intended user path:

mirrorarc --root <vault> code doctor
mirrorarc --root <vault> code analyze --repo <repo-id>
mirrorarc --root <vault> catalog --html

The implementation uses CodeGraph v1.5.0 through ordinary bounded CLI subprocesses. The standalone installer was downloaded and run in an isolated temporary home and install directory. The verified installer SHA-256 was f4e90c6e0c1d2ac95a43fa6e82e4caf76fabdb18310afc72597314b58632e56c; the Darwin arm64 bundle SHA-256 was cf5ee435a6e44d097b2f98f2b7b8b9422bb1094844404efed82519c5da1af2cf. The installed binary reported 1.5.0. No global installation, agent configuration, MCP setup, daemon, deployment, or publication was performed.

The adapter, snapshot/cache service, governed context integration, CLI, Catalog report, and portable Code view are implemented under src/mirrorarc/. Recorded v1.5.0 JSON contracts and focused tests live under tests/fixtures/codegraph_v1_5_0/ and tests/test_code_intelligence.py. README, quickstart, product, profile-schema, security, recovery, software-project profile, ignore rules, no-data enforcement, and changelog guidance are updated.

Clean-wheel proof used a fresh Python 3.11 build environment, a separate runtime environment, and a disposable copy of the Ontario example. pip check reported no broken requirements. code doctor returned Ready with all managed subprocess privacy variables set. The known demand_change symbol resolved to src/grid_evidence/summary.py:8-11; tests/test_summary.py was reported as a medium- confidence symbol-impact candidate, while the normal test gate remained authoritative. Analysis code_analysis_c33d269bdd50e489c1ae40a0ec61 produced frozen context context_6395658f0ebf78a40464990f99b4. Every cited path, line range, and file hash was checked against the disposable source tree.

A controlled source edit changed the local revision and produced a distinct analysis identity, while retaining the prior result and marking its frozen context stale. A forced provider failure returned exit status 1 and retained the prior valid evidence with visible failed state. Moving the entire disposable code-intelligence cache outside the vault produced no-analysis; two independent rebuilds then reproduced analysis code_analysis_9749672969a3d740aee0cbe4d7cc and content hash 750b1a39386afa1bac75e4d9c100c93c23fb2298fcd49ae188cdb8672fe78789 exactly.

Browser proof used the installed wheel's generated HTML, not a development-only UI. The no-analysis, current, stale, and failed states all showed their reason and next action. Current evidence showed the revision, languages, files, exact paths/lines/hashes, ordered call path, impact, affected-test candidate, warnings, and context action. Only the latest analysis appeared in the browse graph after historical reanalysis. A 390 by 844 viewport remained usable; keyboard navigation reached and activated the code-context selection, changing its count from zero to one. All browser journeys had zero console errors or warnings. The HTML application initiated no local process or secondary network fetch.

Privacy and recovery checks confirmed that provider indexes exist only beneath .mirrorarc/cache/code-intelligence/, never in the governed source repository; default Catalog HTML omits code bodies; --include-content includes only bounded selected excerpts; provider environment variables disable telemetry and update checks; and the isolated provider home contains no agent configuration. Ignore rules and the no-data scanner reject tracked or staged .codegraph/ state.

Final local validation on 2026-08-12:

  • focused repository-intelligence/context/privacy suite with real provider smoke: 58 passed;

  • complete repository suite with real provider smoke: 552 passed in 241.26 seconds;

  • template-copy drift check: clean;

  • no-data scan: OK;

  • canonical template lint: OK, including zero unresolved links, orphans, or overlaps;

  • Python compilation and shell syntax checks: passed;

  • fresh wheel build, install, dependency check, workflow, rebuild, and browser proof: passed.

Known limitations are intentional first-release boundaries: Python is the proven language path; affected tests are candidates rather than test-selection authority; local dirty repositories are bound to a deterministic local-tree hash rather than a commit; CodeGraph v1.5.0 is the only supported provider; and analysis remains an explicitly invoked, disposable local read model rather than a watcher, daemon, MCP service, vector store, hosted service, or browser-side engine.

439 files · 404 not served here

Advantages

Limitations

  • No ZIP download: install it from its source (a rule-derived fact from the brain’s files)

Security

Risk level: Low risk

This brain runs

Git hooks (1)

  • .githooks/pre-commit (pre-commit): runs on git pre-commit

Agent instructions that run or fetch something (2)

  • AGENTS.md: Operator direction (2026-09-18): project development and validation run locally.
  • AGENTS.md: Every behavior change: run the package-owned vault lint through the example's tool shim, run the test suite, and update `CHANGELOG.md` and relevant docs.

Install scripts (1)

  • scripts/init.sh: sh scripts/init.sh
  • Low risk: scripts-present (.githooks/pre-commit)
  • Low risk: scripts-present (scripts/init.sh)

Attribution and licence

First committed by
GitHub avatar of cz1993cz1993
Declared authors
  • cz1993 (declared in pyproject.toml)
Publisher
Ci Zhu (Community)
Source
cz1993/MirrorArc · commit 1df13eb
Licence
GNU Affero General Public License v3.0 only (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
cz1993

AutoGineer is not affiliated with or endorsed by cz1993.

Install from source

404 of its files are not served here, so there is no ZIP. cz1993/MirrorArc at 1df13eb