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/RECOVERY.md

Recovery Guide

Purpose

MirrorArc must be recoverable because it works near authoritative business records. Recovery procedures preserve the core promise: source files stay untouched, generated mirrors can be regenerated, derived relationship/view/context state can be rebuilt, and authoritative or reviewed Markdown can be restored from versioned backups.

What To Back Up

Back up the whole vault before first sync and before bulk changes:

  • original source folders;

  • authoritative Markdown records and governed reviewed-view artifacts;

  • _meta/source-manifest.json;

  • _meta/repo-manifest.json;

  • _meta/sync-audit.jsonl;

  • log.md;

  • tools/repos.yml;

  • .mirrorarc/state.sqlite and any SQLite journal sidecars;

  • _meta/knowledge-views/, _meta/review-ledger.jsonl, and persisted context definitions;

  • frozen evidence under .mirrorarc/cache/context/ and historical answer candidates under .mirrorarc/cache/pageindex/<source-id>/answers/ when retaining an audit trail;

  • .obsidian/ settings only if the operator intentionally versions them.

Do not back up secrets into the vault. Keep tokens in the OS keychain or environment. Hidden directories are part of the backup. A folder named cache is not a promise that every file inside it can be recreated: a model answer and its exact frozen evidence are historical records, even though neither becomes source authority.

Stop watchers, scheduled syncs and other writers before taking a whole-vault filesystem copy. Close their database connections and checkpoint SQLite before copying; do not copy only the main database from a running vault and omit its journal. If writers cannot be stopped, use a SQLite-consistent backup procedure and coordinate it with the source/artifact snapshot. This guide's local drill covers a quiescent vault, not a live multi-writer or cloud-sync snapshot.

Restore a whole vault

  1. Preserve the damaged vault separately. Do not restore over an active workspace or writer.

  2. Copy the complete backup, including hidden state and audit evidence, into a new local folder.

  3. Compare the restored file inventory and SHA-256 hashes with the backup before running tools.

  4. Use the same validated MirrorArc and optional-provider versions. Reconfigure credentials outside the vault; do not copy secrets into the backup.

  5. Run mirrorarc --root /absolute/path/to/restored-vault recovery --json, then inspect relationships export, view status --json, context status --json and document status --json. Compare saved review decisions and source/frozen hashes with the backup, not only counts.

  6. Resolve reported conflicts before sync. Run lint and regenerate the Catalog before resuming normal work. A previously saved Catalog is a snapshot, not a live recovery check.

The October 3 local installed-wheel drill restored 84 synthetic-vault files at a new path with identical hashes. It preserved a reviewed view, six frozen packs, one scripted historical answer candidate and an accepted synthetic relationship-review decision. Those fixtures are not human acceptance of a release. Repeat the drill for the operator's actual storage and backup system.

Copied-Vault Sandbox Preflight

Before piloting on a real document collection, duplicate the source collection and run MirrorArc only in the copied vault. Then run the read-only sandbox report:

python3.11 tools/mirrorarc.py sandbox --source-root /path/to/original-documents
python3.11 tools/mirrorarc.py sandbox --source-root /path/to/original-documents --json

The report verifies that the pilot vault is not the same path as the original source root, checks required MirrorArc files/tools, counts source candidates, flags generated source mirrors sitting outside _mirrors/, summarizes manifest/audit/recovery readiness, and checks basic git backup posture. It does not print source paths, document text, mirror text, or repository document bodies. Treat sandbox errors as blockers before the first sync. Treat warnings as review items to resolve or explicitly accept in the private pilot worksheet.

Regenerate Generated Mirrors

After verifying the whole-vault backup, identify generated mirror paths in the source and repo manifests. Move only those generated artifacts to a separately named recovery folder outside the vault; preserve annotations and reviewed Markdown first. Do not use a blanket deletion of source folders or assume a hard-coded repository-note directory is correct for the current profile. Then rebuild from the original sources:

python3.11 tools/mirrorarc.py plan
python3.11 tools/mirrorarc.py sync
python3.11 tools/mirrorarc.py status
python3.11 tools/mirrorarc.py lint

Review the plan before sync if the source tree changed, especially after folder renames or cloud sync conflicts.

Full sync remains the authoritative recovery mode after Stage 1B. If journal state is lost or suspect, stop any watcher, preserve the database, and rebuild operational state from sources and manifests through reconciliation or full sync. The journal is not source authority, but the shared database also contains review decisions that must not be discarded as disposable cache.

The same .mirrorarc/state.sqlite boundary owns relationship, dependency, L2, review, and context metadata through versioned migrations. Rebuild deterministic state from sources, manifests, profile rules, and governed definitions; preserve accepted semantic evidence, reviewed outputs, and frozen packs separately long enough to reattach or audit them. Compare identity, hash, and count reports before accepting recovery.

Current recovery automatically reattaches hash-verified reviewed/pinned L2 Markdown, persisted dynamic context definitions, and frozen context packs during a full deterministic relationship refresh. It reconstructs their artifact and dependency records without rewriting persisted bytes. Semantic proposal/review decisions are not derivable from source files. Retain the SQLite database in normal backups if those decisions must survive total database loss. A relationship-ledger export is useful audit evidence, but there is no automatic ledger-import restore command. Do not treat an export alone as a tested substitute for the database backup. The local drill confirmed both sides of this boundary: deterministic rebuild omitted the synthetic semantic decision, and restoring the saved database recovered it exactly.

Repository analysis is disposable derived state under .mirrorarc/cache/code-intelligence/. If its index, analysis pointers, or snapshots are suspect, remove that directory only, then rebuild from the governed repository identity:

mirrorarc --root <vault> code doctor
mirrorarc --root <vault> code analyze --repo <repo-id>
mirrorarc --root <vault> code status --repo <repo-id>

Deleting this cache does not remove the repository, its L1 mirror, or manifests. Frozen code context files under .mirrorarc/cache/context/ are also derived; preserve one separately only when its exact offline evidence envelope is needed for audit. A failed refresh retains the prior valid analysis and reports failed until a successful rebuild.

Rebuild PDF indexes without losing answer history

PageIndex stores current index pointers, hash-addressed index JSON, and historical answer candidates under .mirrorarc/cache/pageindex/<source-id>/. Before maintenance, back up that source's whole directory together with its frozen packs under .mirrorarc/cache/context/. Answers are not recreated by model-free indexing; asking the same question again is a new inference, not a restore.

For index-only loss, preserve the answers/ subdirectory. Move only the selected source's index JSON files and current.json to a recovery folder outside the vault, then run:

mirrorarc --root /absolute/path/to/restored-vault document doctor
mirrorarc --root /absolute/path/to/restored-vault document status --source SOURCE_ID --json
mirrorarc --root /absolute/path/to/restored-vault document index --source SOURCE_ID --json
mirrorarc --root /absolute/path/to/restored-vault catalog --html --include-content

Use the source ID from the restored manifest. Do not add --model-assisted or --allow-model merely to perform a restore. A source/parser change can legitimately produce a new index identity; historical answers must remain historical. The local drill rebuilt unchanged source evidence with the same index and frozen-pack identities, preserved all answer/frozen bytes, and made no model call.

Applied journal events now record hash-aware invalidation through that dependency graph. A failed or skipped event does not advance invalidation state. mirrorarc reconcile also compares current manifest hashes with ledger artifact hashes and repairs a missed transition; repair uses the same bounded, cycle-safe affected-subgraph traversal as live replay.

Recover From Interrupted Sync

Mirror writes are atomic, so an interrupted sync should preserve either the prior complete mirror or the new complete mirror. A hard interruption can also leave a hidden atomic temp file such as .registration.md.12345.tmp beside the target. After interruption:

python3.11 tools/mirrorarc.py status
python3.11 tools/mirrorarc.py recovery
python3.11 tools/mirrorarc.py sync
python3.11 tools/mirrorarc.py lint

If _meta/source-manifest.json, _meta/repo-manifest.json, or _meta/sync-audit.jsonl is missing, restore it from backup when possible. If no backup exists, rerun status/sync to rebuild manifests from the current sources and mirrors, then review all planned, stale, source_missing, unreachable, and manual_modification states.

Interrupted Stage 1B changed-file materialization should first be inspected with mirrorarc journal status and recovered with mirrorarc journal replay. Replay recovers events left in processing; use mirrorarc journal replay --retry-failed only when a failed event is ready for an explicit retry. Use mirrorarc reconcile to queue missed source/manifest events before replaying recovered work, or use mirrorarc sync --changed to run those two steps as one changed-file pass. mirrorarc watch --once runs the same startup reconciliation posture plus any queued feed work for a deterministic one-cycle watch check. When changed sync, replay, reconciliation, or watch startup cannot prove consistency, run full sync as the recovery path.

When an error state exists, inspect the newest _meta/sync-audit.jsonl event for that source_id or repo_id. The event records the generated artifact path, lifecycle state, sync status, and structured warnings / errors without embedding source document text or repo document bodies. When the vault has _meta/lifecycle-states.yml, source/repo manifest records and audit events also identify that lifecycle contract path and schema version so reviewers can tie a state back to the operator contract used by sync.

Important limitation: without the old manifest, MirrorArc cannot prove whether an existing generated region is pristine. Existing Office and repo mirrors without a manifest-generated baseline are treated as review-required, and --force will not accept them as clean. If the sentinel boundary is valid, run mirrorarc migrate annotations --write to preserve any legacy above-sentinel annotations before regenerating from the original source. If the sentinel is missing or altered, restore the mirror from backup or remove the untrusted mirror after preserving any deliberate human authority in a declared source record, then regenerate from the source.

Recovery Report

Use the read-only recovery report before changing files:

python3.11 tools/mirrorarc.py recovery
python3.11 tools/mirrorarc.py recovery --worksheet
python3.11 tools/mirrorarc.py recovery --runbook
python3.11 tools/mirrorarc.py recovery --json

The report reads _meta/source-manifest.json, _meta/repo-manifest.json, _meta/lifecycle-states.yml, tools/repos.yml, and the latest matching events in _meta/sync-audit.jsonl, then lists only records that need operator action. It does not move, delete, regenerate, or archive anything. Use --worksheet when you need a Markdown review checklist for a private pilot record before changing files. Use --runbook when you need a state-grouped execution protocol for resolving the queue in a controlled batch. Treat recovery output as triage evidence for:

  • planned, source_changed, source_moved, stale, converter_changed, unsupported, source_missing, manual_modification, conflict, and error Office records;

  • missing generated mirror paths;

  • planned, repo_changed, stale, unreachable, repo_unconfigured, manual_modification, conflict, and error repo records;

  • previously synced repo manifest records whose tools/repos.yml entry is now missing, even before the repo sync has persisted repo_unconfigured back to _meta/repo-manifest.json;

  • missing repo mirror notes;

  • stale atomic temp files left by interrupted writes.

The JSON form includes summary.total, summary.office, summary.repo, and summary.temp counts for automation, plus the same item-level reasons, fallback actions, warnings, errors, and latest audit context as the human report. Office and repo items also include a structured lifecycle object from _meta/lifecycle-states.yml with entry_condition, explanation, permitted_next_actions, exit_condition, and manifest_state. The worksheet prints the contract-backed explanation, next actions, and exit condition for each item so operators can see how to leave the state safely. The runbook form groups the same queue into resolution paths for missing Office sources, moved sources, repo mirrors whose config entry was removed, manual generated-region edits, conflicts or errors, and stale atomic temp files. It prints execution rules and verification gates, but does not change files. For Office move and mirror-root conflict records, the report also includes previous_target, previous_target_exists, and previous_target_reason so operators can identify the retained generated mirror that must be preserved, moved, archived, or removed before syncing again. For ambiguous move conflicts, the report and Office manifest record include ambiguous_move_candidates with the missing source paths whose bytes match the new source. Choose the correct history manually, or preserve/archive the old mirrors and treat the new file as a deliberate duplicate or new source before rerunning sync. The human report shows a bounded candidate summary with a total count; use mirrorarc recovery --json when the full candidate list is longer than the human summary. For manifest repair mistakes where multiple non-synthetic records claim the same current source path, the report includes duplicate_source_ids. Correct the duplicate manifest records before syncing; MirrorArc will not choose one source history silently.

For each item with audit history, the report includes the latest audit timestamp, status, lifecycle state, lifecycle contract provenance when available, and structured warnings/errors. This is diagnostic metadata only; it should not contain raw document text or repo documentation bodies.

For temp:interrupted_write items, rerun status/sync first to confirm the canonical generated file or manifest is complete. Then remove the temp file after backup review; MirrorArc does not delete it automatically.

For Office conflict records caused by a mirror-root or mirror-mode change, archive or remove the previous generated mirror after review. MirrorArc will not write the new mirror path while the old generated mirror still exists, because that would leave two generated notes claiming the same source.

For Office source_moved records with previous_mirror_path, migrate any legacy annotations from the old mirror, then move, archive, or remove that previous generated mirror. MirrorArc will not write the new mirror path while the old generated mirror still exists.

For Office conflict records with ambiguous_move_candidates, do not force sync. Multiple missing manifest records have identical bytes, so MirrorArc cannot prove which prior source path moved. Use the candidate paths, old mirrors, and Git history/backups to choose the correct source record; if you want to preserve one candidate's source history, edit or restore the manifest deliberately. If the new file should be treated as a deliberate new or duplicate source, either restore the candidate source files to their manifest paths so they are no longer missing, or deliberately edit or remove the old candidate manifest records after preserving their old mirrors. Simply moving the old files to an archive path without manifest resolution leaves the original manifest paths missing and the conflict active. Rerun status after the resolution; the conflict clears once fewer than two matching missing candidates remain.

For Office conflict records with duplicate_source_ids, do not sync until the manifest has a single non-synthetic source record for that current source path. Keep the source ID whose history is correct, restore the other source files to their actual paths or archive their mirrors deliberately, then rerun status.

If a manifest is missing, restore it from backup when possible. Without manifest evidence, MirrorArc cannot safely prove whether an existing generated region is pristine.

Recover From Bad Generated Output

If extraction quality is poor or a converter update produces worse markdown:

  1. Restore the prior mirror from Git or backup if humans need the previous readable output.

  2. Keep the original source file unchanged.

  3. Pin or revert the converter dependency if needed.

  4. Run tools/mirrorarc.py status and inspect converter-related stale states.

  5. Record the decision in log.md.

If conversion fails before writing, MirrorArc records an error lifecycle state and leaves the previous mirror untouched. Fix the converter/source issue, rerun tools/mirrorarc.py sync, then confirm tools/mirrorarc.py status returns the source to clean.

If writing the mirror fails, MirrorArc records an error lifecycle state and leaves the previous mirror untouched. Fix the filesystem, permission, disk-space, or cloud-sync issue, rerun tools/mirrorarc.py sync, then confirm the source returns to clean.

Repo mirror note writes follow the same rule: a write failure records an error lifecycle state, keeps the previous repo note, and can recover to clean after the filesystem issue is fixed and sync is rerun.

Recover Authoritative Markdown and Reviewed Views

Authoritative Markdown is human-maintained source evidence. Reviewed L2 output is a governed derived version. Restore both from Git or filesystem backup, not from a generated candidate. If an agent made a bad edit:

git diff
git restore -- path/to/note.md
python3.11 tools/mirrorarc.py lint

Only restore with explicit owner approval when the note contains current business decisions.

Source Missing Review

MirrorArc does not delete mirrors automatically when a source disappears. A missing source means:

  • the source was intentionally moved or deleted;

  • a cloud-sync file is not pinned locally;

  • a path changed;

  • a backup or restore is incomplete.

Resolve the source first. If the deletion is intentional, archive or remove the mirror through a human-reviewed change and keep the audit trail.

Release Gate

Before public release, recovery must be tested on a copied vault:

  • run tools/mirrorarc.py sandbox --source-root <original-source-root> and resolve errors;

  • move generated _mirrors/ aside into a recovery folder and regenerate;

  • interrupt sync and rerun;

  • force a converter failure and verify the previous mirror is preserved, then fix the converter and verify sync returns the record to clean;

  • force a mirror-write failure and verify the previous mirror is preserved, then fix the filesystem issue and verify sync returns the record to clean;

  • force a repo-note write failure and verify the previous repo note is preserved, then fix the filesystem issue and verify sync returns the record to clean;

  • remove one source and verify source_missing;

  • change one source and verify source_changed, change mirror configuration and verify stale, and change converter metadata or version and verify converter_changed;

  • configure one new source/repo and verify planned;

  • change one repo fixture or HEAD and verify repo_changed, make a configured repo unreachable and verify unreachable, then remove a synced repo config entry and verify repo_unconfigured;

  • edit a generated region and verify manual_modification;

  • move one source and verify source_moved blocks new mirror generation while the previous mirror exists, then remove or move the previous mirror and verify the new mirror can be generated;

  • change the Office mirror root with the old mirror present and verify conflict, then remove the old mirror and verify the new mirror can be generated;

  • run tools/mirrorarc.py recovery and verify the checklist matches the manifest states;

  • restore an authoritative Markdown record and a reviewed-view version from Git;

  • preserve .mirrorarc/state.sqlite outside the copied vault, rebuild deterministic relationships/views, and compare current hashes and counts before accepting recovery; verify reviewed/pinned views, dynamic definitions, and frozen packs reattach with unchanged bytes;

  • run no-data scan and lint after recovery.

Stage 1B adds recovery gates for journal replay, missed-event reconciliation, stale-lock recovery, duplicate event delivery, crash after mirror write but before checkpoint, and full-sync recovery after journal loss. The current replay path covers interrupted processing events and explicit failed-event retry; the current explicit reconciliation path queues missed create, update, delete, move, and review-required candidate events; the current watch --once path runs deterministic startup reconciliation, feed queueing, and replay; manifest-backed deleted events now mark records source_missing while retaining generated mirrors; resolved source_moved records replay after old-mirror cleanup, and delete/recreate can return records to clean. Optional watch --native capture now maps watchdog events through the same feed/replay boundary. The Stage 1B safety-gate closure records focused, affected, full-suite, packaging, lint, no-data, template-copy, shell syntax, diff, and residue validation.

The test suite now exercises the copied-vault regeneration path, source-byte preservation, converter-failure, Office mirror-write-failure, and repo-note write-failure recovery that preserve the prior generated file, interrupted-write temp detection, conversion-race aborts that preserve the prior mirror, source_missing, manual_modification, lint, and generated-text no-data scan checks on the Northwind example. Example regeneration tests also assert source bytes stay unchanged across plan, dry-run, sync, status, and lint operations, and that stable generated outputs remain unchanged across a second sync. The installed-wheel synthetic drill also passed copied-vault sandbox checks with zero errors, generated-mirror loss/rebuild, lint, and a no-data scan of the generated HTML, mirror and reviewed view. Sandbox warnings about a missing unused repo manifest and the parent Git workspace were retained; no files were staged or committed. Operator backup/restore drills and full copied-vault no-data scans on actual pilot vaults remain required before production use.

A snapshot-identity mismatch indicates a source mutation during copying or modified disposable cache. The operation fails without replacing the prior valid analysis. Confirm the source is stable, remove only the disposable code-intelligence cache, and retry once; do not remove sources or frozen audit evidence. --base REF compares the base commit to the analyzed working tree, including staged, unstaged and untracked paths, with both sides of renames and deleted-path omissions. It is not a committed merge-base-to-HEAD comparison.

Full mirrorarc sync reconciles manifest hash changes through the existing dependency invalidator, including marking frozen contexts stale while preserving their bytes. Query refresh performs the same reconciliation before graph replacement, so a refresh cannot erase the previous hash first.

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