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

PageIndex local validation results

Updated October 4, 2026. MirrorArc remains unreleased and not accepted for enterprise use. This record distinguishes actual runtime checks from model-quality evidence and owner acceptance. The release plan remains the full finish line.

What is implemented

The optional PageIndex 0.2.10+mirrorarc.1 worker indexes one registered PDF, validates physical page references, reuses governed context policies, and publishes immutable evidence. Model calls require an explicit endpoint, model and command opt-in. The CLI exposes readiness, indexing, questions and status. The local Catalog presents source-page evidence and unreviewed answer candidates with their frozen excerpts; it does not run inference or approve claims.

The source revision is upstream 6d23caf416858f2ca136840305d1f479a86f6ef7, plus the separately identified local parser patch and hashed dependency recipe. The patched runtime uses Python 3.11.15, pypdf 6.19.0, pypdfium2 5.13.0, LiteLLM 1.103.2, OpenAI 2.54.0, OpenAI Agents 0.20.0 and HTTPX 0.28.1. The core package does not install this dependency tree. The local suffix identifies a MirrorArc patch, not an upstream release.

Original-runtime release blocker, locally mitigated: a pip-audit 2.10.1 audit found PYSEC-2026-1835 / CVE-2023-36464 in PyPDF2 3.0.1. A crafted PDF can cause an infinite loop. The upstream advisory lists no patched PyPDF2 release and recommends migrating to maintained pypdf. The worker's timeout limits a hang; it does not patch the parser. The existing runtime is retained as reproduction evidence, not approved for release or use with untrusted documents. The replacement removes PyPDF2 entirely, migrates PageIndex's imports to maintained pypdf, and refuses the original runtime. Provider and parser versions are bound into evidence; an upgrade requires reindexing and marks older answer candidates historical without overwriting their frozen packs.

Fresh audits reported no known vulnerabilities in published dependencies in either the 81-package locked provider environment or the 38-package core wheel environment. The local PageIndex patch and MirrorArc distribution were skipped because those versions are not published on PyPI. This is not a source-code or native-library security audit. Both environments passed dependency checks. A separate development-environment audit flagged pytest 9.0.2; that temporary test runtime was upgraded to 9.0.3 before the final upstream suite. Test tools are not in the optional runtime lock.

Evidence and limits

CheckEvidence establishedWhat it does not establish
Model-free extractionActual PageIndex reads a synthetic three-page PDF; physical page 2 contains the expected interval; no model HTTP requestOCR coverage, arbitrary-document conversion quality or answer quality
Model-free change trialEditing 30 days to 14 days invalidates current use; refreshed evidence has a new identity; old frozen bytes surviveA real business-policy change or model reasoning
API integrationActual SDK talks to a scripted loopback peer for assisted indexing and tool-driven questions; selected page text reaches the second question requestAny model's reasoning quality, external endpoint compatibility or paid-provider result
Astra context trialEight real Codex-subscription cases over synthetic PageIndex-extracted evidence; both plain and governed inputs met the core grounding checksBetter answers than plain text, direct SDK model transport, automatic retrieval, independent judging or release acceptance
Boundary enforcementInvalid configuration, wrong operation/model, output budget, response storage, request size/count, oversized responses, redirects and unapproved Python network/process operations are refusedAn OS sandbox, native-parser security audit or dollar-spend guarantee
Citation integritySource rename, cache tamper and a changed index during pack freezing cannot silently produce mixed-version evidenceSemantic entailment or a guarantee that every claim has sufficient support
Parser migration321 focused upstream checks; final upstream suite 721 passed, 100 skipped; end-of-file comment regression completes; PyPDF2 absentOptional Anthropic/Claude integrations or PageIndex cloud tests, which account for the skips; arbitrary hostile PDF safety
Reproducible setupFresh checkout accepts the packaged patch; hash-enforced dependency install and pinned-backend source build succeed; doctor imports offlineBit-for-bit reproducible wheel archives or a Linux runtime result
Installed packageFresh core wheel executes doctor, forced indexing, frozen-page export, status and Catalog; all 77 package Python files and four recipe assets match the checkoutRelease acceptance or live-provider model behavior
Repository integrationRestored checksum-verified CodeGraph 1.5.0; 21-command installed-wheel journey passes source-span, stale/failure, frozen-history and cache-rebuild checksWhole private-repository coverage or Linux proof
Operational recoveryQuiescent 84-file synthetic-vault backup restored at a new path; derived database, PDF index and generated mirror rebuilt; six frozen packs, one reviewed view and one scripted historical answer preservedA live-writer/cloud-sync backup or restore on the operator's production storage
CatalogCurrent, stale and damaged candidate states inspected in the browser; keyboard citation expansion; literal script-like text; desktop and 390-pixel text wrappingIndependent-user acceptance or automatic review decisions

The initial full suite after integration was 580 passed and one optional CodeGraph smoke skipped. A subsequent hardening run passed 590 tests with that same skip in 261.69 seconds. The combined hardening suite then passed 591 tests, with one optional CodeGraph smoke skipped, in 267.46 seconds. Those runs used the original PyPDF2 runtime and did not clear the dependency blocker. After migration, 24 focused MirrorArc regressions passed. The full suite against the locked patched runtime passed 593 tests, with one optional CodeGraph smoke skipped, in 277.33 seconds. CodeGraph 1.5.0 was subsequently restored in an isolated private folder, with no global installation. Its Darwin arm64 archive matched the published SHA-256 cf5ee435a6e44d097b2f98f2b7b8b9422bb1094844404efed82519c5da1af2cf; all 912 installed files matched that verified archive. The final combined suite with both optional providers passed 594 tests, zero skips, in 269.03 seconds. The current installed wheel also passed the separate 21-command CodeGraph journey. Its source and recipe files still match the checkout; subsequent edits in this pass are documentation only, not a new package build.

The runtime-validation wheel and sdist built successfully before the later documentation edits. The wheel SHA-256 is cf8bd9d97f06983c129a1b4e5c678b60459d9f2ffc70466ab2a993d0aba8267f and the sdist SHA-256 is 15de06b44c28d65d61ae0e94e47bffc92fb314b80321db68c7b3471f3434c7c0. The fresh installed-wheel journey preserved the synthetic source and both pre-existing frozen packs. A second installed-wheel run started with actual legacy-runtime evidence: current use was refused, reindexing succeeded under pypdf, and all three older frozen packs remained unchanged. Example-owned shim lint passed for 44 notes / 80 files with all reported warning and error categories zero. No-data, template-copy and diff-format checks passed. These are local release checks, not enterprise acceptance.

The durable local review folder is MirrorArc-Private-Reviews/2026-10-03 under the operator's Documents directory. pageindex-proof-06/REVIEW.html is the earlier model-free owner exercise, with rendered source-page images because the in-app browser's PDF view was blank. All six PDF pages were rendered and visually inspected. wheel-cli-proof-02/proof.json records the fresh installed-package journey; wheel-cli-proof-03/proof.json records the legacy-to-pypdf migration. pageindex-locked-audit.json, core-pypdf-wheel-audit.json, pypdf-full-tests.xml and pypdf-upstream-all-loopback-tests.xml retain audit/test evidence. answer-ui-proof-02/ is an earlier scripted API/UI contract test, explicitly not model quality. The historical September Trustworthy Context handoff remains a historical record; its temporary paths and fingerprints must not be treated as the current shipment evidence.

Astra subscription trial

On October 4 the owner accepted the shorter authored review layout and authorized testing with the same model as the planning session through the existing Codex subscription, without a user-imposed spending cap. These are separate decisions: neither accepts the enterprise release.

Eight real GPT-6 Astra cases completed through Codex CLI 0.160.0 with max reasoning effort and normal ChatGPT authentication. The installed standalone CLI 0.149.0 was refused by the service as too old for Astra; using the existing app-bundled CLI succeeded without a global upgrade or credential extraction. This records the tested local versions, not a universal minimum version.

Actual installed MirrorArc and PageIndex generated fresh evidence for three synthetic PDFs. The harness supplied all three pages either as plain extracted text or as a governed frozen pack. Both arms received identical page bodies and the same answer instructions. Each arm ran a before, after, conflicting-evidence and unsupported-question case once. The after case received that arm's earlier answer as explicitly historical context. All eight runs recorded zero model tool calls; the harness, not the model, selected the pages. No private source was deliberately supplied.

The planning-session agent inspected every unedited answer against the predeclared rubric and the rendered source pages. Both arms met the four core grounding checks: 30 days before the edit, 14 days after it, visible 14-versus-30 disagreement without invented precedence, and no invented purchase price. The fault exception was retained. This was not a blinded or independent evaluation.

CasePlain text wordsGoverned evidence words
Before5461
After6469
Conflict7273
Unsupported question3642

Counts are whitespace-separated words in the answer, reason and warning, including citation markers, not hidden reasoning. Governed answers were slightly longer in every matched case. No answer-correctness, comprehension, verification-time or latency advantage was established. The independently checked product benefit was traceability: both source edits marked old packs stale, while earlier frozen bytes remained unchanged before and after inference.

One temporal-wording issue remains: the governed after answer says it “corrects” the prior answer, although that answer matched the old PDF. Future wording should say the source changed instead of implying the earlier interpretation was erroneous. The original output remains unedited.

Durable evidence is under MirrorArc-Private-Reviews/2026-10-04/astra-subscription-trial-01 in the operator's Documents directory. trial-spec.json precedes the calls; trial-results.json and the per-case prompt, answer and event files retain actual inference evidence; assessment.json records the findings; evidence-proof.json records source and pack hashes. The passive REVIEW.html contains the actual outputs and linked source-page images. Its default view has 182 visible words; desktop, 390-pixel width, keyboard disclosure and source-image navigation were checked. All nine PDF pages were visually inspected. These local artifacts are not public repository data.

This trial did not exercise the SDK's direct model-assisted indexing, document ask model transport/publication, automatic evidence selection or production answer UI. The separate authored-layout approval is recorded in the earlier local review package. Owner judgment of this real-model report and implementing the accepted layout in the product were still open at that historical checkpoint. The follow-up below records subsequent runtime changes and new validation separately.

Answer clarity follow-up — October 4

The actual worker now requests a direct answer, cited reason, visible important caveats and optional detail. New records label the optional answer-first-v1 contract while preserving the complete original output. Backend previews parse only that explicit layout; older or unreadable layouts fall back to escaped full text with a warning. Catalog puts answer review before general metadata and document navigation, keeps freshness/unreviewed state visible, and opens frozen page excerpts from keyboard-accessible citations. No model, freshness calculation or review action runs in the browser. Default exports omit the question, answer, presentation and excerpts.

New local evidence is in MirrorArc-Private-Reviews/2026-10-04/clarity-development-01 under the operator's Documents directory. It is separate from the historical results above:

  • The full suite passed 606 tests, with one optional CodeGraph smoke skipped, in 278.08 seconds. The explicit CodeGraph suite then passed all eight tests, including that smoke. The final renderer ordering adjustment received the affected focused checks and installed-wheel journey.

  • Example-owned shim lint after the documented plan/sync step passed for 44 notes / 80 files with all reported issue categories zero. Template-copy, no-data and diff-format checks passed.

  • The fresh installed wheel exercised CLI document ask with the actual pinned SDK against a scripted two-request loopback peer, plus doctor, status and metadata-only Catalog commands. All 78 package Python files matched the checkout. Current/stale/damaged Catalog snapshots preserve the generated answer and frozen evidence; this is transport/presentation proof.

  • The production Catalog was inspected at desktop and 390-pixel widths in current, stale and unavailable states. Keyboard citation activation opens and focuses the frozen excerpt, script-like text remains literal, and unavailable evidence suppresses the answer. No horizontal document overflow was observed. This was developer review, not owner acceptance.

  • Five new GPT-6 Astra cases completed through bundled Codex CLI 0.160.0, normal subscription authentication, max effort and zero model tool calls. The exact product reading instructions were tested with the existing synthetic page bodies. Before/after, conflict, unknown price and missing change-provenance cases all met the predeclared checks on primary-agent inspection. The after case described a verified source change, not a wrong earlier answer. The case without comparison evidence refused to establish a change. Raw outputs and prompts are retained.

There was one run per model case, no blinded or independent judge and no new comparison arm. The harness supplied every page and supplied verified change provenance only to the after case. This does not establish an answer-quality advantage or validate direct SDK real-model inference. The earlier eight unedited outputs and their temporal-wording finding remain historical evidence.

Validation setup failures are retained too: a first full-suite invocation used a relative PYTHONPATH, breaking subprocess imports; its 129 failures / 477 passes / one skip are not a product verdict. The corrected absolute-path invocation produced the result above. The initial no-data scan caught generated Python/pytest caches, which were moved outside the repository; subsequent checks used external caches or disabled bytecode. Direct lint of the ungenerated example reported its expected missing mirrors; the documented copied-example plan/sync/lint journey passed. An initial UI fixture retained a legacy parser index and was correctly refused until reindexed.

Planning-session acceptance, owner judgment, real SDK model validation, Linux proof and shipment remain open. No global installation, commit, push, merge, remote change, release or deployment was performed.

Backup and recovery evidence

operational-recovery-03/proof.json, its command transcript and backup manifest record 28 actual installed-wheel CLI commands against a synthetic copy. Every one of the 84 backed-up files matched after restoration at a new path. Database loss and deterministic refresh reattached the reviewed view, dynamic definitions, all six frozen packs and the PDF index without changing their persisted evidence. Removing only index JSON and its pointer, while retaining answers/, reproduced the same current index and frozen-pack identities with zero model requests. Moving generated mirrors aside produced an actionable recovery item; sync recreated the PDF mirror from unchanged source. Lint and the generated HTML/mirror/reviewed-view no-data scan passed. The input fixture, complete backup and quarantined recovery evidence were preserved.

The semantic relationship-review decision was deliberately absent after source-only database reconstruction, then recovered exactly by restoring the database backup. The reviewer name was explicitly a synthetic fixture, not owner approval. The historical answer was produced by an earlier scripted loopback peer, not a real model. These distinctions are part of the proof.

The initial sandbox had zero errors and retained warnings: no repository manifest was needed in the PDF-only vault, and the private review directory is inside an unrelated parent Git workspace. The evidence files were verified untracked there; no files were staged, committed or published in that parent repository. Keep backups outside publication paths and repeat the drill on actual pilot storage. The first drill attempt stopped because the harness added native Markdown without explicitly refreshing deterministic relationships. The corrected run performs that documented step; this was a harness correction, not a hidden product fix.

Additional durable evidence is all-providers-full-tests.xml, codegraph-wheel-journey-01/journey.json, codegraph-1.5.0-proof/ and the private validate_operational_recovery.py drill. The recovery guide now distinguishes index maintenance from answer-history retention and database restoration from source-only reconstruction.

What remains before release

  1. Complete real-model validation of the supported SDK indexing/question workflow. The approved Codex evidence trial is complete; do not ask again for its model or spending cap or present it as proof of the untested direct SDK route. Any different inference route needs explicit scope.

  2. Review and accept the locally implemented concise presentation and temporal-wording instructions in the actual product. Obtain owner judgment of actual generated answers and verification effort; the authored-layout approval and eight-case self-review cannot supply that judgment.

  3. Re-audit at shipment and review maintenance of the local provider patch. Complete Linux validation and deployment hardening. The local synthetic restore drill is complete; the operator runbook requires repeating it on actual storage before a production deployment. The October 3 check found no available Docker daemon or Colima instance. Linux testing is deferred for the Mac owner pilot, not removed from release requirements; no VM was created.

  4. Review the combined dirty tree and its final fingerprint. Keep pre-existing changes in scope rather than treating the current HEAD as a complete description of the work.

  5. Obtain acceptance and confirm shipment scope. The current workflow definitions were inspected: PR/main activity can run hosted CI, this batch matches the main-branch Pages deployment paths, and v* tags trigger a draft prerelease. Resolve those automatic effects before the single owner-authored PR/merge, then rebuild final artifacts from the accepted tree. No commit, push, workflow edit, remote-setting change, release or deployment was performed in this validation pass.

The request-attempt guard follows the distinction between per-attempt timeouts and total retry budgets in official OpenAI rate-limit guidance. Provider-side budget and retention controls still require operator review.

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