MercuryToolbox/docs/maintainer-notes.md

Maintainer Notes

This document captures the project decisions that are easy to lose between implementation rounds. Treat it as the quick orientation page for future workers before changing Mercury Toolbox internals.

Project Direction

• Mercury Toolbox is not trying to replace every Unix utility. It adds a high-signal layer for local inspection, structure extraction, diagnostics, and AI/model handoff.
• Default text output should stay compact and human-scannable. Use structured output only when the next consumer benefits from it.
• The priority order for JSON-family and code-reading work is capability first, then speed, then memory/CPU footprint, then binary size. All four matter, but do not shrink a tool by removing useful behavior.
• Windows PowerShell UX is a first-class target. Prefer stdin, path streams, clear examples, and failure messages that tell the user what to try next.

Code Shape Family

• codeindex is the shared AST/indexing engine. outline, codeshape, defsnip, and refs should reuse it instead of growing separate parsers.
• Tree-sitter support exists to make language coverage better, not just faster. When improving outline-like behavior, prefer AST-backed extraction over regex-only expansion.
• If a language has weak output, add tests that demonstrate the missing constructs before tuning presentation. Java feedback was the first strong signal, but the goal is broad polyglot usefulness.
• Keep outline short and readable by default. Use codeshape, defsnip, refs, snip, and ctxpack for deeper or wider context.

JSON-Family Tools

• common::formats::{toon, ison, zon, tonl} is the shared home for compact JSON-family logic. Binaries should be thin CLIs around shared Rust implementations.
• Do not introduce Node, npm, TypeScript, Python, or Go runtime dependencies for these formats. Official repositories/specs/fixtures are comparison sources only.
• Every JSON-capable Mercury tool should route structured output through the shared renderer and support --json, --toon, and --format text|json|toon.
• --json stays for compatibility. --toon is the AI-friendly shortcut. MERCURY_OUTPUT=json|toon|text is the session-wide default when no explicit format flag is provided.
• The standalone toon binary remains useful for external JSON producers. For Mercury tools, prefer native --toon; for path streams, prefer simple pipelines such as fd ... | fileprobe --input-format lines --toon.
• toon auto-detects JSON input and emits TOON by default. Avoid documenting long forms like --json | toon --from json --to toon unless a specific conversion direction truly needs to be explicit.
• Shared TOON decoding must preserve quoted literal keys, reject strict dotted-path conflicts, and round-trip what the shared encoder emits, including root arrays and root primitives.
• tonl is more than a converter. Preserve query, validate, index, streaming query, and ETL behavior when refactoring.

Jade Is Mandatory

• Jade has no optional safety tier. Miri, fuzzing, sanitizers, no-panic scanning, and Loom are part of the main gate.
• scripts/check-jade.ps1 is the authoritative full gate. If a worker only runs a focused loop such as just fuzz or just loom, they have not run Jade.
• Exemptions are allowed only through explicit -Exempt* flags with non-empty reviewed reasons. Missing tools, awkward platforms, or slow checks are failures by default.
• The independent fuzz/ workspace is intentional. Keep its Cargo.lock committed, keep fuzz/.gitignore preventing corpus/artifact leaks, and keep root Jade auditing fuzz dependencies with udeps, locked metadata, and cargo deny.
• The no-panic gate scans JSON-family production paths for panic!, .unwrap(), and .expect(). Prefer fallible propagation. If a panic surface is truly unavoidable, use the strict adjacent comment form // jade: allow-panic because: <reason>.
• Sanitizer setup is platform-sensitive. Windows needs ASan runtime discovery; non-Windows must not fail because a Windows DLL is absent.
• Loom tests should model production-like concurrency patterns, not unrelated toy examples. Keep the runtime capture model tied to join/publish behavior.

Documentation And Generated Assets

• README.md is the user-facing map. docs/jade-discipline.md is the safety/verification contract. This file is maintainer orientation.
• Generated AI prompt and skill assets must be changed through scripts/generate-ai-prompt.ps1 and scripts/generate-ai-skill.ps1; do not hand-edit generated output unless the generator changes in the same patch.
• For docs, script, justfile, template, or generated-check hygiene, just periphery-check is the focused local proof. It is not a substitute for just jade when Rust behavior or release readiness is in scope.
• For docs-only maintenance, prefer a small proof ladder: just --summary, just ai-check when generated asset references are touched, and just periphery-check before handoff if PowerShell scripts, just recipes, or generated-check expectations are mentioned.
• When a pass receives a numeric candidate quota, record the reviewed count and the skipped classes in .codex-progress\quality-security-backlog.md; do not create low-value edits just to hit the number.
• Help examples should teach the happy path and the AI-friendly path. Favor examples like --toon or --json | toon only when they shorten the real user workflow.
• If a tool accepts path input, keep PowerShell wildcard behavior in mind. Native glob expansion is not guaranteed, so either support globs deliberately or give fd ... | tool --input-format lines guidance.
• The vendored tree-sitter crate is intentionally pinned through [patch.crates-io]; follow vendor/tree-sitter/README.md before updating or re-vendoring it.

CI And Runner Handoff

• The hosted Gitea CI lane uses the dedicated windows runner label, records a toolchain snapshot, runs just workspace-check, then performs explicit cargo nextest, strict Clippy, and just ecosystem-fast steps.
• Treat the toolchain snapshot as runner drift evidence. If cargo nextest --version, cargo llvm-cov --version, just --version, or pwsh --version is missing or surprising, fix the runner/tooling before changing repository gates.
• The release workflow is tag-driven and expects the tag to match [workspace.package].version; do not document a release as published until the package exists and the Gitea release upload has actually succeeded.
• scripts\setup-gitea-runner.ps1 creates local runner state and .runner credentials on the host. Treat those files and any GITEA_TOKEN / GITEA_API_TOKEN values as secret material that must stay out of docs, screenshots, package archives, and commits.
• Before and after authenticated Gitea work, use secret-residue checks such as git remote -v, .git\config, and targeted rg scans for Authorization, GITEA_TOKEN, and token-bearing URLs. Report only the fact that the check passed, not token values.
• When CI behavior changes, update the README workflow overview, this maintainer note, and the daily backlog together so future workers know whether a failing step is expected duplication, runner drift, or a new regression.

Moving Or Relocating The Repo

• Scripts should be path-independent and derive the workspace root from $PSScriptRoot where possible.
• Do not hardcode local worktree paths in documentation or scripts.
• This repository may be moved between drives. After moving a Git worktree layout manually, verify both the main worktree and linked worktrees with git status --short.

Gitea HTTPS Credential Fallback

• Symptom: Git for Windows can show a git-remote-https.exe application error while a push, fetch, or ls-remote operation is resolving HTTPS credentials. In the observed failure, direct authenticated API checks still worked, and a one-shot Git command with a Basic auth header worked, so the failure belonged to the local Git HTTPS credential path rather than repository contents.
• First repair the machine when possible: update Git for Windows, update Git Credential Manager, and check whether the host certificate chain is trusted by the active Git TLS backend. Those changes belong on the affected machine, not in this repository.
• Repo-safe fallback: use scripts\invoke-gitea-git.ps1 for Gitea Git commands that need authentication. It sets credential.helper= for that invocation, uses http.sslBackend=openssl, injects an http.extraHeader Basic auth header, disables terminal prompts, clears Git curl tracing while the header is in scope, and filters libcurl trace lines from captured Git stderr.
• Pass a token with -ApiToken or set GITEA_API_TOKEN/GITEA_TOKEN only in the current shell. The helper deliberately does not fall back to Git Credential Manager; if no token is provided, it fails closed instead of re-entering the crash path.
• Keep TLS verification on by default. Use -InsecureSkipTlsVerify only as a temporary test-host workaround, then remove it once the certificate chain is fixed.
• After any emergency authenticated push, verify that git remote -v and .git\config contain no token, no Authorization header, and no credential-bearing URL.