polymath-nexus 0.2.0__tar.gz

polymath_nexus-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayushi Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

polymath_nexus-0.2.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: polymath-nexus
+Version: 0.2.0
+Summary: Long-term team brain — markdown + JSONL, date-stamped, owner-attributed, append-only. Auto-generates CLAUDE.md / AGENTS.md / .cursor / Copilot mirrors so every AI tool reads it for free.
+Author: Ayushi Gupta
+License: MIT
+Project-URL: Homepage, https://github.com/ayushigupta-29/nexus
+Project-URL: Repository, https://github.com/ayushigupta-29/nexus
+Project-URL: Format spec, https://github.com/ayushigupta-29/nexus/blob/main/SPEC.md
+Keywords: ai,memory,context,team-brain,claude,cursor,codex,copilot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: embed
+Requires-Dist: google-genai>=1.0.0; extra == "embed"
+Requires-Dist: openai>=1.50.0; extra == "embed"
+Requires-Dist: sqlite-vec>=0.1.6; extra == "embed"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+# nexus — long-term team brain
+
+> *nexus* (Greek: νοῦς) — mind, intellect, intuition.
+> The faculty that sees things as they are.
+
+`nexus` is a long-lived, team-shareable project memory. It is:
+
+- **Just markdown files in a folder.** No DB to run, no server to host.
+- **Date-stamped and owner-attributed.** Every entry carries
+  `[YYYY-MM-DD owner]`. Grep works forever.
+- **Append-only.** Nothing is ever auto-deleted. Old engineering rules
+  are load-bearing, not stale.
+- **Tool-agnostic.** Auto-generates `CLAUDE.md`, `AGENTS.md`,
+  `.cursor/rules/brain.mdc`, `.github/copilot-instructions.md` —
+  every AI tool you use reads the brain through its native discovery,
+  no extra config.
+- **Forward-compatible.** Schema versioned. A `nexus` from 2046 will
+  still read a brain written in 2026, and vice versa.
+
+## Why
+
+Teams accumulate knowledge faster than they document it. The brain is
+where that knowledge goes to live for decades — surviving turnover,
+tool churn, and reorgs.
+
+When someone leaves: their `brain/rules/<them>.md` stays. Their
+decisions, their patterns, their gotchas — all dated, all attributed.
+The next person reads `brain/` on day one and inherits the team's
+mental model.
+
+## Quickstart
+
+```bash
+pip install nexus
+cd ~/my-repo
+nexus init                                # creates brain/ + AI tool mirrors
+nexus learn-from "always use httpx, never requests — async-first codebase"
+```
+
+That's it. Open Claude Code / Cursor / Codex / Copilot in this repo —
+all four now read this rule automatically via their native discovery
+files.
+
+## Folder structure
+
+```
+brain/
+├── README.md                       intro for humans
+├── rules/<owner>.md                hard constraints, never break these
+├── logic/<owner>.md                business/domain logic
+├── code/<owner>.md                 patterns, conventions, architecture
+├── stack/<owner>.md                tech stack, versions
+├── data/<owner>.md                 schemas, field definitions
+├── goals/<owner>.md                project objectives, scope
+├── decisions/<owner>.md            ADR-style: chosen approach + why
+├── glossary/<owner>.md             domain term definitions
+└── personas/<owner>.md             tone, behavior, communication style
+```
+
+Per-owner sub-files mean two teammates writing simultaneously **never
+conflict at the file level**. You can also use single-file mode
+(`brain/rules.md`); the reader handles both.
+
+## CLI
+
+```bash
+nexus init                            # create brain/ in cwd
+nexus learn-from "<rule>"             # append to rules/<you>.md, dated
+nexus show [bucket]                   # grep-first search
+  --since 2026-01-01
+  --until 2026-05-31
+  --by ayushi
+  -q pattern
+  --json
+nexus usage                           # counts per bucket + owner
+nexus own                             # print your owner slug
+nexus sync                            # regenerate AI-tool mirrors
+nexus unmirror                        # remove mirrors (opt-out)
+nexus spec                            # print SPEC.md
+```
+
+## Auto-generated mirrors
+
+After every `nexus` write, four files at repo root are regenerated:
+
+| Mirror | Tool | Auto-discovered |
+|---|---|---|
+| `CLAUDE.md` | Claude Code | ✓ |
+| `AGENTS.md` | Codex CLI | ✓ |
+| `.cursor/rules/brain.mdc` | Cursor | ✓ |
+| `.github/copilot-instructions.md` | GitHub Copilot | ✓ |
+
+Each carries `<!-- GENERATED — DO NOT EDIT -->`. Edit `brain/`; mirrors
+follow. To opt out: `nexus unmirror`.
+
+## Per-team use cases
+
+**Engineering** — Drop your rules in `brain/rules/<you>.md`. Cursor /
+Claude Code / Codex see them all automatically.
+
+**Data** — `brain/glossary/<you>.md` is the canonical home for metric
+definitions. "What does 'active user' mean?" gets answered once,
+forever.
+
+**Analytics** — `brain/decisions/<you>.md` for revenue recognition,
+attribution choices. Date stamps make the rationale auditable.
+
+**Business / PMs** — Edit any `.md` via GitHub web UI; commits become
+PRs through your normal review flow. No CLI required.
+
+## Long-term contracts
+
+- **No auto-delete.** Ever. The brain only grows. Old rules are
+  load-bearing.
+- **Append-only history.** When a rule changes, write a new chunk that
+  `supersedes` the old one; the old one stays on disk forever.
+- **Forward-compat.** Unknown fields in chunk JSONL are dropped on
+  read, not crashed. Your 2026 install reads 2046 brains and vice
+  versa.
+- **No required services.** A brain is markdown files. Anything that
+  reads files reads the brain.
+
+Full format contract: see [`SPEC.md`](./SPEC.md).
+
+## License
+
+MIT.
+
+## Related
+
+Built originally as the substrate layer of
+[polymath](https://github.com/ayushigupta-29/polymath), a multi-model
+AI orchestrator. Extracted into its own repo so any AI tool, not just
+Polymath, can use the format.

polymath_nexus-0.2.0/README.md

@@ -0,0 +1,134 @@
+# nexus — long-term team brain
+
+> *nexus* (Greek: νοῦς) — mind, intellect, intuition.
+> The faculty that sees things as they are.
+
+`nexus` is a long-lived, team-shareable project memory. It is:
+
+- **Just markdown files in a folder.** No DB to run, no server to host.
+- **Date-stamped and owner-attributed.** Every entry carries
+  `[YYYY-MM-DD owner]`. Grep works forever.
+- **Append-only.** Nothing is ever auto-deleted. Old engineering rules
+  are load-bearing, not stale.
+- **Tool-agnostic.** Auto-generates `CLAUDE.md`, `AGENTS.md`,
+  `.cursor/rules/brain.mdc`, `.github/copilot-instructions.md` —
+  every AI tool you use reads the brain through its native discovery,
+  no extra config.
+- **Forward-compatible.** Schema versioned. A `nexus` from 2046 will
+  still read a brain written in 2026, and vice versa.
+
+## Why
+
+Teams accumulate knowledge faster than they document it. The brain is
+where that knowledge goes to live for decades — surviving turnover,
+tool churn, and reorgs.
+
+When someone leaves: their `brain/rules/<them>.md` stays. Their
+decisions, their patterns, their gotchas — all dated, all attributed.
+The next person reads `brain/` on day one and inherits the team's
+mental model.
+
+## Quickstart
+
+```bash
+pip install nexus
+cd ~/my-repo
+nexus init                                # creates brain/ + AI tool mirrors
+nexus learn-from "always use httpx, never requests — async-first codebase"
+```
+
+That's it. Open Claude Code / Cursor / Codex / Copilot in this repo —
+all four now read this rule automatically via their native discovery
+files.
+
+## Folder structure
+
+```
+brain/
+├── README.md                       intro for humans
+├── rules/<owner>.md                hard constraints, never break these
+├── logic/<owner>.md                business/domain logic
+├── code/<owner>.md                 patterns, conventions, architecture
+├── stack/<owner>.md                tech stack, versions
+├── data/<owner>.md                 schemas, field definitions
+├── goals/<owner>.md                project objectives, scope
+├── decisions/<owner>.md            ADR-style: chosen approach + why
+├── glossary/<owner>.md             domain term definitions
+└── personas/<owner>.md             tone, behavior, communication style
+```
+
+Per-owner sub-files mean two teammates writing simultaneously **never
+conflict at the file level**. You can also use single-file mode
+(`brain/rules.md`); the reader handles both.
+
+## CLI
+
+```bash
+nexus init                            # create brain/ in cwd
+nexus learn-from "<rule>"             # append to rules/<you>.md, dated
+nexus show [bucket]                   # grep-first search
+  --since 2026-01-01
+  --until 2026-05-31
+  --by ayushi
+  -q pattern
+  --json
+nexus usage                           # counts per bucket + owner
+nexus own                             # print your owner slug
+nexus sync                            # regenerate AI-tool mirrors
+nexus unmirror                        # remove mirrors (opt-out)
+nexus spec                            # print SPEC.md
+```
+
+## Auto-generated mirrors
+
+After every `nexus` write, four files at repo root are regenerated:
+
+| Mirror | Tool | Auto-discovered |
+|---|---|---|
+| `CLAUDE.md` | Claude Code | ✓ |
+| `AGENTS.md` | Codex CLI | ✓ |
+| `.cursor/rules/brain.mdc` | Cursor | ✓ |
+| `.github/copilot-instructions.md` | GitHub Copilot | ✓ |
+
+Each carries `<!-- GENERATED — DO NOT EDIT -->`. Edit `brain/`; mirrors
+follow. To opt out: `nexus unmirror`.
+
+## Per-team use cases
+
+**Engineering** — Drop your rules in `brain/rules/<you>.md`. Cursor /
+Claude Code / Codex see them all automatically.
+
+**Data** — `brain/glossary/<you>.md` is the canonical home for metric
+definitions. "What does 'active user' mean?" gets answered once,
+forever.
+
+**Analytics** — `brain/decisions/<you>.md` for revenue recognition,
+attribution choices. Date stamps make the rationale auditable.
+
+**Business / PMs** — Edit any `.md` via GitHub web UI; commits become
+PRs through your normal review flow. No CLI required.
+
+## Long-term contracts
+
+- **No auto-delete.** Ever. The brain only grows. Old rules are
+  load-bearing.
+- **Append-only history.** When a rule changes, write a new chunk that
+  `supersedes` the old one; the old one stays on disk forever.
+- **Forward-compat.** Unknown fields in chunk JSONL are dropped on
+  read, not crashed. Your 2026 install reads 2046 brains and vice
+  versa.
+- **No required services.** A brain is markdown files. Anything that
+  reads files reads the brain.
+
+Full format contract: see [`SPEC.md`](./SPEC.md).
+
+## License
+
+MIT.
+
+## Related
+
+Built originally as the substrate layer of
+[polymath](https://github.com/ayushigupta-29/polymath), a multi-model
+AI orchestrator. Extracted into its own repo so any AI tool, not just
+Polymath, can use the format.

polymath_nexus-0.2.0/nexus/__init__.py

@@ -0,0 +1,104 @@
+"""
+Brain — long-term project memory.
+
+This is the public API surface of the brain. Anything not exported here is
+internal to brain and may change without notice. The surface is intentionally
+small — the brain's value is in the *file format* (markdown + JSONL + date
+stamps + owner attribution), not in any specific Python API.
+
+Long-term contract: nothing inside `nexus.*` imports anything from
+`polymath.*` outside the brain. Enforced by tests/test_brain_decoupling.py.
+
+This boundary is what makes the brain extractable into its own package
+later — when that happens, this exact `__init__.py` becomes the top-level
+of the new `brain` distribution.
+
+────────────────────────────────────────────────────────────────────────
+Quick reference
+
+  # Discovery
+  from nexus import find_brain_root, find_repo_root, current_owner_slug
+
+  # Init
+  from nexus import init_brain_root
+
+  # Reading
+  from nexus import read_context, build_context_injection
+  from nexus import brain_grep, brain_usage
+
+  # Writing
+  from nexus import append_context, write_context
+
+  # Types
+  from nexus import TaskType, CONTEXT_FILES, AuthExpiredError
+
+  # Memory (chunked, embedded — optional, opt-in)
+  from nexus import Chunk, MemoryStore, harvest_session
+"""
+from __future__ import annotations
+
+# ── Discovery ────────────────────────────────────────────────────────────────
+from nexus.discovery import (
+    current_owner_slug,
+    find_brain_root,
+    find_repo_root,
+)
+
+# ── Types (canonical home) ───────────────────────────────────────────────────
+from nexus.types import (
+    ALWAYS_INJECT,
+    CONTEXT_DESCRIPTIONS,
+    CONTEXT_FILES,
+    TASK_CONTEXT_MAP,
+    AuthExpiredError,
+    TaskType,
+)
+
+# ── Config ───────────────────────────────────────────────────────────────────
+from nexus.config import (
+    BRAIN_CACHE_DIR,
+    BRAIN_DIR_NAME,
+    BRAIN_HOME,
+    BRAIN_PROJECTS_DIR,
+    MIRROR_FILES,
+)
+
+# ── Index (read/write) ───────────────────────────────────────────────────────
+from nexus.index import (
+    append_context,
+    brain_grep,
+    brain_usage,
+    build_context_injection,
+    context_dir,
+    create_project,
+    init_brain_root,
+    list_context_files,
+    list_projects,
+    read_context,
+    write_context,
+)
+
+# ── Memory (chunked store, optional) ─────────────────────────────────────────
+from nexus.memory.store import Chunk, MemoryStore
+from nexus.memory.writer import (
+    HarvestResult,
+    harvest_session,
+)
+
+__all__ = [
+    # Discovery
+    "current_owner_slug", "find_brain_root", "find_repo_root",
+    # Types
+    "TaskType", "AuthExpiredError",
+    "CONTEXT_FILES", "CONTEXT_DESCRIPTIONS", "TASK_CONTEXT_MAP", "ALWAYS_INJECT",
+    # Config
+    "BRAIN_HOME", "BRAIN_PROJECTS_DIR", "BRAIN_CACHE_DIR", "BRAIN_DIR_NAME",
+    "MIRROR_FILES",
+    # Index
+    "init_brain_root", "create_project", "list_projects",
+    "context_dir", "list_context_files",
+    "read_context", "write_context", "append_context",
+    "build_context_injection", "brain_grep", "brain_usage",
+    # Memory
+    "Chunk", "MemoryStore", "HarvestResult", "harvest_session",
+]

polymath_nexus-0.2.0/nexus/cli.py

@@ -0,0 +1,223 @@
+"""
+`nexus` — standalone CLI for the long-term brain.
+
+No LLM dependencies. Pure stdlib + nexus. Works with `pip install nexus`
+(brain-only) or as a dependency of polymath.
+
+Subcommands:
+    nexus init                          Create brain/ in cwd
+    nexus show [bucket] [--since DATE] [--until DATE] [--by OWNER] [-q PATTERN]
+                                        Search the brain. Grep-first.
+    nexus usage                         Counts per bucket + per owner
+    nexus own                           Print which slug you'll write as
+    nexus learn-from "<correction>"     Append to rules/<you>.md (deliberate)
+    nexus sync                          Regenerate the AI-tool mirror files
+    nexus unmirror                      Remove the AI-tool mirror files
+    nexus spec                          Print the SPEC.md format contract
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from nexus.discovery import current_owner_slug, find_brain_root, find_repo_root
+from nexus.index import (
+    append_context, brain_grep, brain_usage, context_dir, create_project,
+    init_brain_root,
+)
+from nexus.mirrors import regenerate_mirrors, remove_mirrors
+
+
+def _cmd_init(args) -> int:
+    base = init_brain_root(Path(args.cwd) if args.cwd else None)
+    repo = find_repo_root() or base.parent
+    report = regenerate_mirrors(repo_root=repo, force=getattr(args, "force", False))
+    print(f"✓ Brain initialised at {base}")
+    if report.written:
+        for tool, path in report.written.items():
+            print(f"  ↳ mirrored to {path.relative_to(repo)} (for {tool})")
+    elif not report.skipped:
+        print("  (brain is empty; mirrors will be generated after first write)")
+    _print_skipped(report, repo)
+    print(f"\nYour owner slug: {current_owner_slug()}")
+    print("\nNext: `nexus learn-from \"your first rule\"`")
+    return 0
+
+
+def _cmd_show(args) -> int:
+    project = args.project or ""
+    hits = brain_grep(
+        project,
+        pattern=args.pattern or "",
+        since=args.since or "",
+        until=args.until or "",
+        by=args.by or "",
+        ctx_name=args.bucket or "",
+    )
+    if not hits:
+        print("(no matches)")
+        return 0
+    if args.json:
+        print(json.dumps(hits, indent=2))
+        return 0
+    for h in hits:
+        print(f"{h['file']:40s}  {h['text']}")
+    return 0
+
+
+def _cmd_usage(args) -> int:
+    project = args.project or ""
+    stats = brain_usage(project)
+    if args.json:
+        print(json.dumps(stats, indent=2))
+        return 0
+    print(f"Total entries: {stats['total_entries']}\n")
+    if stats["buckets"]:
+        print("By bucket:")
+        for k, v in sorted(stats["buckets"].items(), key=lambda kv: -kv[1]):
+            print(f"  {k:12s}  {v}")
+    if stats["owners"]:
+        print("\nBy owner:")
+        for k, v in sorted(stats["owners"].items(), key=lambda kv: -kv[1]):
+            print(f"  {k:12s}  {v}")
+    return 0
+
+
+def _cmd_own(args) -> int:
+    """Print owner slug and the timezone we'll record on writes."""
+    from nexus.memory.store import _local_tz_name
+    print(f"owner: {current_owner_slug()}")
+    print(f"tz:    {_local_tz_name()}")
+    return 0
+
+
+def _cmd_learn_from(args) -> int:
+    text = args.text or ""
+    if not text:
+        print("usage: nexus learn-from \"<rule>\"", file=sys.stderr)
+        return 2
+    project = args.project or ""
+    brain = find_brain_root()
+    if brain is None and not project:
+        # Need either a brain/ in cwd or a project name for personal scope.
+        print("error: no brain/ found in this repo. Run `nexus init` first,\n"
+              "or use --project <name> for personal-scope brains.", file=sys.stderr)
+        return 1
+    if not brain and project:
+        create_project(project)
+    owner = current_owner_slug()
+    written = append_context(project, "rules", text, by_owner=True, author=owner)
+    print(f"✓ Logged to {written.relative_to(written.parents[2]) if len(written.parents) >= 3 else written}")
+    _dt = __import__("datetime").datetime
+    today = _dt.now().astimezone().strftime("%Y-%m-%d")
+    print(f"  - [{today} {owner}] {text}")
+    return 0
+
+
+def _print_skipped(report, repo: Path) -> None:
+    """Tell the user about mirror files we refused to overwrite. Silence
+    here would look like the mirror simply worked."""
+    for tool, path in report.backed_up.items():
+        print(f"  ↳ saved your old {tool} file to {path.relative_to(repo)}")
+    if not report.skipped:
+        return
+    for tool, path in report.skipped.items():
+        print(f"  skipped {path.relative_to(repo)} — you wrote this, not nexus")
+    print("  Move its content into brain/, or run with --force to hand it "
+          "over (your version is saved as a .bak first).")
+
+
+def _cmd_sync(args) -> int:
+    repo = find_repo_root() or (find_brain_root() or Path.cwd()).parent
+    report = regenerate_mirrors(args.project or "", repo_root=repo, force=args.force)
+    if not report.written and not report.skipped:
+        print("(brain is empty; nothing to mirror)")
+        return 0
+    for tool, path in report.written.items():
+        print(f"✓ {tool}: {path.relative_to(repo)}")
+    _print_skipped(report, repo)
+    return 0
+
+
+def _cmd_unmirror(args) -> int:
+    report = remove_mirrors(force=args.force)
+    for p in report.removed:
+        print(f"removed {p}")
+    for p in report.skipped:
+        print(f"kept {p} — you wrote this, not nexus")
+    if report.skipped:
+        print("Pass --force to delete it anyway.")
+    if not report.removed and not report.skipped:
+        print("(no mirror files present)")
+    return 0
+
+
+def _cmd_spec(args) -> int:
+    spec = Path(__file__).resolve().parent / "SPEC.md"
+    if spec.exists():
+        print(spec.read_text())
+        return 0
+    print(f"SPEC.md not found at {spec}", file=sys.stderr)
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="nexus",
+        description="Long-term, team-shareable project brain.",
+    )
+    p.add_argument("--project", default="", help="project name (personal scope)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init", help="create brain/ in cwd")
+    p_init.add_argument("--cwd", default="", help="target directory (default: cwd)")
+    p_init.add_argument("--force", action="store_true",
+                        help="take over mirror files you wrote by hand (saves a .bak)")
+    p_init.set_defaults(func=_cmd_init)
+
+    p_show = sub.add_parser("show", help="search the brain (grep-first)")
+    p_show.add_argument("bucket", nargs="?", default="", help="one of: rules logic code stack data goals decisions glossary personas")
+    p_show.add_argument("--since", default="", help="YYYY-MM-DD lower bound")
+    p_show.add_argument("--until", default="", help="YYYY-MM-DD upper bound")
+    p_show.add_argument("--by", default="", help="owner slug")
+    p_show.add_argument("-q", "--pattern", default="", help="substring filter (case-insensitive)")
+    p_show.add_argument("--json", action="store_true", help="emit JSON")
+    p_show.set_defaults(func=_cmd_show)
+
+    p_usage = sub.add_parser("usage", help="counts per bucket and per owner (read-only)")
+    p_usage.add_argument("--json", action="store_true")
+    p_usage.set_defaults(func=_cmd_usage)
+
+    p_own = sub.add_parser("own", help="print which owner slug you'll write as")
+    p_own.set_defaults(func=_cmd_own)
+
+    p_learn = sub.add_parser("learn-from", help="log a correction to rules/<you>.md")
+    p_learn.add_argument("text", nargs="?", default="", help="the rule to log")
+    p_learn.set_defaults(func=_cmd_learn_from)
+
+    p_sync = sub.add_parser("sync", help="regenerate AI-tool mirror files")
+    p_sync.add_argument("--force", action="store_true",
+                        help="take over mirror files you wrote by hand (saves a .bak)")
+    p_sync.set_defaults(func=_cmd_sync)
+
+    p_unmirror = sub.add_parser("unmirror", help="remove AI-tool mirror files")
+    p_unmirror.add_argument("--force", action="store_true",
+                            help="also delete mirror files nexus did not write")
+    p_unmirror.set_defaults(func=_cmd_unmirror)
+
+    p_spec = sub.add_parser("spec", help="print the brain SPEC.md")
+    p_spec.set_defaults(func=_cmd_spec)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())