@ahmed-g-gad/apothem 0.1.1 → 1.0.0

package/CHANGELOG.md

@@ -7,7 +7,7 @@ All notable changes to this project are documented in this file.
 This changelog follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.1] - 2026-06-27
+## [1.0.0] - 2026-07-03
 
 The first release of Apothem — a host-agnostic configuration manager that
 authors one shared profile and materializes it into the native configuration of
@@ -30,8 +30,8 @@ reproducible releases.
   `~/.apothem/backups/` before replacement; uninstalls reverse cleanly with zero
   orphans.
 - **CLI.** `quickstart`, `install`, `uninstall`, `update`, `verify`, `status`,
-  `diff`, `rollback`, `harnesses`, `profile`, `doctor`, and `completion`
-  commands, with dry-run reporting, drift detection, structured JSON output
+  `diff`, `rollback`, `migrate-workspace`, `harnesses`, `profile`, `doctor`, and
+  `completion` commands, with dry-run reporting, drift detection, structured JSON output
   (`--format json`), and per-harness status. The engine is self-contained — the
   source tree carries its vendored dependencies and runs from a checkout as
   `python -m apothem` on system Python 3.10+.
@@ -57,4 +57,4 @@ reproducible releases.
   documentation build, CodeQL, OpenSSF Scorecard, dependency audit, and
   supply-chain checks before publication.
 
-[0.1.1]: https://github.com/Ahmed-G-Gad/apothem/releases/tag/v0.1.1
+[1.0.0]: https://github.com/ahmed-g-gad/apothem/releases/tag/v1.0.0

package/README.md

@@ -12,14 +12,15 @@
 <h1 align="center">Apothem</h1>
 
 <p align="center">
-  <em>One shared profile · materialized into seventeen assistant harnesses.</em>
+  <em>Author one shared profile · materialize it into seventeen tools' native configs.</em>
 </p>
 
 <p align="center">
+  <a href="https://github.com/ahmed-g-gad/apothem/releases"><img alt="Release" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapothem.ahmedgad.com%2Fbadges%2Frelease.json"></a>
   <a href="https://github.com/ahmed-g-gad/apothem/actions/workflows/ci.yml"><img alt="Build" src="https://github.com/ahmed-g-gad/apothem/actions/workflows/ci.yml/badge.svg?branch=main"></a>
   <a href="https://github.com/ahmed-g-gad/apothem/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/ahmed-g-gad/apothem?color=0F172A"></a>
   <a href="https://www.npmjs.com/package/@ahmed-g-gad/apothem"><img alt="npm version" src="https://img.shields.io/npm/v/%40ahmed-g-gad%2Fapothem?color=10B981&label=npm"></a>
-  <a href="https://github.com/ahmed-g-gad/apothem/actions/workflows/ci.yml"><img alt="Coverage" src="https://img.shields.io/badge/coverage-%E2%89%A580%25-2563EB"></a>
+  <a href="https://github.com/ahmed-g-gad/apothem/blob/main/pyproject.toml"><img alt="Coverage gate ≥80%" src="https://img.shields.io/badge/coverage%20gate-%E2%89%A580%25-2563EB"></a>
   <a href="https://securityscorecards.dev/viewer/?uri=github.com/ahmed-g-gad/apothem"><img alt="OpenSSF Scorecard" src="https://api.securityscorecards.dev/projects/github.com/ahmed-g-gad/apothem/badge"></a>
   <a href="https://github.com/ahmed-g-gad/apothem/discussions"><img alt="Community discussions" src="https://img.shields.io/badge/discussions-GitHub-7C3AED"></a>
   <a href="https://apothem.ahmedgad.com/"><img alt="Documentation" src="https://img.shields.io/badge/docs-Fumadocs-0F172A"></a>
@@ -27,14 +28,18 @@
 </p>
 
 <p align="center">
+  <a href="https://github.com/ahmed-g-gad/apothem#why-apothem">Why Apothem</a>
+  &nbsp;·&nbsp;
   <a href="https://github.com/ahmed-g-gad/apothem#install">Install</a>
   &nbsp;·&nbsp;
   <a href="https://github.com/ahmed-g-gad/apothem#quick-start">Quick Start</a>
   &nbsp;·&nbsp;
-  <a href="https://apothem.ahmedgad.com/">Documentation</a>
+  <a href="https://github.com/ahmed-g-gad/apothem#how-it-works">How it works</a>
   &nbsp;·&nbsp;
   <a href="https://github.com/ahmed-g-gad/apothem#supported-harnesses">Supported harnesses</a>
   &nbsp;·&nbsp;
+  <a href="https://apothem.ahmedgad.com/">Documentation</a>
+  &nbsp;·&nbsp;
   <a href="https://github.com/ahmed-g-gad/apothem/blob/main/CHANGELOG.md">Changelog</a>
   &nbsp;·&nbsp;
   <a href="https://github.com/ahmed-g-gad/apothem/blob/main/CONTRIBUTING.md">Contributing</a>
@@ -50,7 +55,7 @@
   </a>
 </p>
 
-**Apothem** authors one shared profile — rules, slash-commands, skills, hooks, output-styles, settings (including MCP servers), schemas, and docs — and materializes that *whole synced unit* into all seventeen supported harnesses' native configuration directories through per-harness adapters. One source of truth. Seventeen destinations. Zero hand-maintained drift. A mechanized conformity gate keeps every materialized surface in line.
+**Apothem** authors one shared profile — rules, slash-commands, skills, hooks, output-styles, settings (including MCP servers), schemas, and docs — and materializes that *whole synced unit* into all seventeen supported harnesses' native configuration directories through per-harness adapters. Edit the profile once; every tool picks up the change from a single command. One source of truth, seventeen destinations, zero hand-maintained drift — with a mechanized conformity gate keeping every materialized surface in line.
 
 ## Why Apothem
 
@@ -59,9 +64,9 @@ Supported harnesses proliferate; each one parks its configuration in a different
 Apothem cuts the drift at the root, and goes wider than file-copying or rules-only sync:
 
 - **One profile, seventeen destinations.** Author your rules, slash-commands, skills, hooks, output-styles, settings (MCP servers included), schemas, and docs once. Push the whole unit to every harness with one command.
-- **A wide synced unit, not rules alone.** Rules · slash-commands · skills · hooks · output-styles · settings (with MCP servers) · schemas · docs travel together as first-class primitives — translated into each harness's native schema, not flattened to a lowest common denominator.
+- **A wide synced unit, not rules alone.** Every primitive travels as a first-class citizen — translated into each harness's native schema, never flattened to a lowest common denominator.
 - **A mechanized governance gate.** `python -m apothem.conformity.gate` runs multi-bar pre-emission checks — authorship headers, naming, code-craft, hedging, binding reciprocity — so every materialized surface stays conformant.
-- **Deterministic pipelines.** A review pipeline (`/plan-spec → /plan-generate → /plan-review → /plan-design → /plan-execute`, where `/plan-design` runs only for architecture-bearing suites), a 13-stage `/research` pipeline, and an eleven-command audit fortress apply to every change to the profile itself.
+- **Deterministic pipelines.** A review pipeline (`/plan-spec → /plan-generate → /plan-review → /plan-design → /plan-execute`, where `/plan-design` runs only for architecture-bearing suites), a thirteen-stage `/research` pipeline, and an eleven-command audit fortress apply to every change to the profile itself.
 - **Reversible, verified lifecycle.** Every install is undone by the matching uninstall — timestamped backups, zero orphans; `apothem verify --harness <name>` answers "is the profile faithfully installed here?" with a structured JSON drift report.
 - **Durable memory + opt-in learning.** A persistent memory tier and an opt-in continuous-learning loop carry confirmed conventions forward across sessions.
 - **Work that survives session, account, and machine boundaries.** Long-running work externalizes its full state to a project-local `.apothem/plans/` suite — a resumption contract plus a cold-start protocol. Because the state lives in your project's files, not locked inside one cloud chat history, a fresh session on any account or machine pointed at the project picks the work back up in place. See [Resumable planning](https://apothem.ahmedgad.com/docs/concepts/resumable-planning/).
@@ -73,7 +78,7 @@ Apothem cuts the drift at the root, and goes wider than file-copying or rules-on
 | 🎯 | **One profile → seventeen native configs** | Author once; install everywhere. Each harness receives the profile translated into its own native schema — no lowest-common-denominator flattening. |
 | 🧩 | **A wide synced unit** | Rules · slash-commands · skills · hooks · output-styles · settings (with MCP servers) · schemas · docs travel together as first-class primitives — not rules alone. |
 | 🛡️ | **Mechanized governance gate** | `python -m apothem.conformity.gate` runs multi-bar pre-emission checks — authorship headers, naming, code-craft, hedging, binding reciprocity — across every materialized surface; a behavior-diff golden corpus regression-locks each adapter's output, so any unintended change to what a harness receives is caught. |
-| 🧭 | **Deterministic pipelines** | A staged `/plan` review pipeline and a 13-stage `/research` pipeline apply the same discipline to every change to the profile itself. |
+| 🧭 | **Deterministic pipelines** | A staged `/plan` review pipeline and a thirteen-stage `/research` pipeline apply the same discipline to every change to the profile itself. |
 | 🏰 | **eleven-command audit fortress** | Security · code · accessibility · performance · dependency · supply-chain · threat-model · architecture · code-review · docs-review · UX audits on demand. |
 | 🧠 | **Durable memory + opt-in learning** | A persistent memory tier and an opt-in continuous-learning loop carry confirmed conventions forward across sessions. |
 | 👁️ | **Preview before write** | `apothem diff --harness <name>` shows every pending change to a harness's native config before anything lands — inspect the full diff, then install. |
@@ -85,19 +90,19 @@ Apothem cuts the drift at the root, and goes wider than file-copying or rules-on
 
 ## How Apothem compares
 
-Other tools solve adjacent slices of this problem. File-based config managers like **chezmoi** and **GNU Stow** place or template files but never translate one source into each harness's *native* configuration schema. Cross-tool rule-sync CLIs like **rulesync** do generate per-tool native files across many tools — a broader tool count than Apothem's seventeen. Apothem's distinction is the **breadth of the synced unit** and the discipline shipped around it:
+Other tools solve adjacent slices of this problem. File-based config managers like **chezmoi** and **GNU Stow** place or template files but never translate one source into each harness's *native* configuration schema. Cross-tool rule-sync CLIs like **rulesync** do generate per-tool native files across many tools — a broader tool count than Apothem's seventeen, and a comparably wide synced unit. Apothem's distinction is the **governance and lifecycle discipline shipped around the sync** — a mechanized conformity gate, deterministic pipelines, an audit fortress, and a reversible verified lifecycle:
 
 | Capability | Apothem | File config managers<br>(chezmoi, Stow) | Cross-tool rule sync<br>(rulesync) | Per-tool native config |
 |---|:---:|:---:|:---:|:---:|
 | One source → many tools' native schemas | ✅ seventeen harness adapters | ❌ copy / symlink, no translation | ✅ | ❌ single tool |
-| Synced unit | rules · slash-commands · skills · hooks · output-styles · settings (MCP) · schemas · docs | arbitrary files | rules · MCP · commands | — |
+| Synced unit | rules · slash-commands · skills · hooks · output-styles · settings (MCP) · schemas · docs | arbitrary files | rules · ignore · MCP · commands · subagents · skills · hooks · permissions | — |
 | Mechanized governance gate | ✅ `python -m apothem.conformity.gate` | ❌ | ❌ | ❌ |
-| Deterministic `/plan` + 13-stage `/research` pipelines | ✅ | ❌ | ❌ | ❌ |
+| Deterministic `/plan` + thirteen-stage `/research` pipelines | ✅ | ❌ | ❌ | ❌ |
 | eleven-command audit fortress | ✅ security · perf · a11y · supply-chain · … | ❌ | ❌ | ❌ |
 | Durable memory + opt-in learning loop | ✅ | ❌ | ❌ | ❌ |
 | Reversible, verified lifecycle | ✅ backup + `apothem verify` + zero-orphan uninstall | varies | varies | — |
 
-Where a peer is stronger, it is named: **rulesync** reaches more tools, and several sync tools materialize native schemas. Apothem trades raw tool count for a wider synced unit — skills, hooks, MCP servers, and the command pipelines as first-class, not rules alone — and the governance, audit, and review discipline that ships with it.
+Where a peer is stronger, it is named: **rulesync** reaches more tools and carries a comparably wide synced unit, and several sync tools materialize native schemas. Apothem trades raw tool count for the governance, audit, and lifecycle discipline shipped around the sync — a conformity gate, deterministic `/plan` and `/research` pipelines, an eleven-command audit fortress, durable memory, and a reversible verified lifecycle — that a rule-sync tool does not carry.
 
 ## Quick Start
 
@@ -116,8 +121,9 @@ npx @ahmed-g-gad/apothem verify --harness claude-code
 
 That is the whole path: `quickstart` scaffolds a shared profile when none
 exists, previews every file it will write, installs, and names the next
-commands; `verify` reports whether the profile is faithfully installed. The rest
-of this section is the longer tour.
+commands; `verify` reports whether the profile is faithfully installed. What
+follows is the longer tour — the same one command explained in full, then the
+explicit step-by-step alternative.
 
 ### Other ways to install
 
@@ -137,16 +143,14 @@ curl -fsSL https://apothem.ahmedgad.com/install.sh | sh    # POSIX
 irm https://apothem.ahmedgad.com/install.ps1 | iex         # Windows
 ```
 
-The guided first step is a single command that walks the whole canonical path —
-create a shared profile if none exists, preview the files each harness will
-write, confirm, then install:
+The `quickstart` command walks the whole canonical path in one guided step:
 
 ```shell
 npx @ahmed-g-gad/apothem quickstart
 ```
 
-`quickstart` ensures a profile (scaffolding one with a personalize nudge if it
-is missing), previews the writes grouped by project root versus your home
+It ensures a profile (scaffolding one with a personalize nudge if it is
+missing), previews the writes grouped by project root versus your home
 directory, asks before writing outside the project, installs with the grouped
 capability-note output, and ends by naming the next commands. `--yes` runs it
 non-interactively; `--format json` emits one structured summary.
@@ -182,8 +186,36 @@ Every install path runs the same self-contained engine: the source tree
 carries its vendored dependencies and runs from a checkout on system Python
 3.10 or newer (see
 [the self-contained runtime](https://apothem.ahmedgad.com/docs/architecture/self-contained-runtime/)).
+Two prerequisites are shared by every path — **system Python 3.10 or newer** on
+`PATH`, with the `click` and `rich` packages importable under it; the npm-shim
+and tool-plugin paths additionally need **Node.js 18 or newer** to run `npx`.
+
+Eight install channels are available. Pick by how you already work; each
+channel's own subsection below gives its prerequisites, one copy-ready command,
+and a verification step.
+
+| # | Channel | Delivers | Prerequisites |
+|---|---|---|---|
+| 1 | [Claude Code plugin](#1--claude-code-plugin) | Full harness in Claude Code | Claude Code · Python 3.10+ |
+| 2 | [npm shim (`npx`)](#2--npm-shim-npx) | Full harness, any tool | Node 18+ · Python 3.10+ |
+| 3 | [One-shot installers](#3--one-shot-installers) | Full harness + an `apothem` command | Python 3.10+ (`git` for a network install) |
+| 4 | [VS Code family extension](#4--vs-code-family-extension) | Full harness from the editor | VS Code · Node 18+ · Python 3.10+ |
+| 5 | [Gemini CLI extension](#5--gemini-cli-extension) | Bootstrap that runs the engine | Gemini CLI · Node 18+ · Python 3.10+ |
+| 6 | [Qwen Code extension](#6--qwen-code-extension) | Bootstrap that runs the engine | Qwen Code · Node 18+ · Python 3.10+ |
+| 7 | [Codex plugin](#7--codex-plugin) | Bootstrap that runs the engine | Codex · Node 18+ · Python 3.10+ |
+| 8 | [Direct engine (`python -m apothem`)](#8--direct-engine-python--m-apothem) | Full harness from a checkout | Python 3.10+ (`click`, `rich`) |
+
+The npm shim (2), the one-shot installers (3), and the direct engine (8)
+deliver the whole synced unit for any harness. The Gemini CLI, Qwen Code, and
+Codex extensions (5–7) install a small bootstrap that shells out to the engine
+(`npx @ahmed-g-gad/apothem install`) to materialize the full harness — they are
+the entry point, not the full delivery on their own.
+
+Every path is idempotent: re-running is safe and converges to the same state.
+
+### 1 — Claude Code plugin
 
-### Claude Code plugin
+**Prerequisites:** Claude Code, and system Python 3.10+ on `PATH`.
 
 Inside Claude Code:
 
@@ -192,10 +224,18 @@ Inside Claude Code:
 /plugin install apothem@apothem
 ```
 
-### npx
+**Verify:** run `/help` inside Claude Code and confirm the Apothem commands are
+listed, or check the drift report with:
 
-The npm shim locates Python 3.10+ and forwards every CLI command to the
-bundled engine:
+```shell
+npx @ahmed-g-gad/apothem verify --harness claude-code
+```
+
+### 2 — npm shim (`npx`)
+
+**Prerequisites:** Node.js 18+ (for `npx`) and system Python 3.10+ on `PATH`.
+The shim locates the interpreter and forwards every CLI command to the bundled
+engine.
 
 ```shell
 npx @ahmed-g-gad/apothem install --harness claude-code
@@ -207,7 +247,18 @@ It also runs straight from the repository:
 npx github:ahmed-g-gad/apothem install --harness claude-code
 ```
 
-### One-shot installers
+**Verify:**
+
+```shell
+npx @ahmed-g-gad/apothem --version
+npx @ahmed-g-gad/apothem verify --harness claude-code
+```
+
+### 3 — One-shot installers
+
+**Prerequisites:** system Python 3.10+ on `PATH` (the installer offers to add
+the `click` / `rich` prerequisites for you); `git` is needed only for a network
+install that clones the source.
 
 The one-shot installer resolves the latest signed release tag, verifies its
 signature, fetches the Apothem source tree at that tag, runs the engine
@@ -219,6 +270,16 @@ tag-pinned verified install is the default and recommended path.
 | **POSIX** (macOS / Linux / WSL) | `curl -fsSL https://apothem.ahmedgad.com/install.sh \| sh` |
 | **Windows** (PowerShell) | `irm https://apothem.ahmedgad.com/install.ps1 \| iex` |
 
+The same scripts ship in a checkout under
+[`scripts/installer/`](scripts/installer/) — `install`, `uninstall`, and
+`update` in `.sh`, `.ps1`, and `.bat` forms — so you can run them directly
+after cloning:
+
+```shell
+APOTHEM_HARNESS=claude-code sh scripts/installer/install.sh                                 # POSIX
+$env:APOTHEM_HARNESS = 'claude-code'; pwsh -NoProfile -File scripts/installer/install.ps1   # Windows
+```
+
 **Trust model (tag-pinned, verified by default).** With no `APOTHEM_REF` set,
 the installer resolves the highest `vMAJOR.MINOR.PATCH` release tag and checks
 *that* out — never the moving `main` branch. Before any configuration is
@@ -266,7 +327,7 @@ dependencies) — POSIX into `$HOME/.local/bin`, Windows into
 `%LOCALAPPDATA%\Microsoft\WindowsApps` (a user directory already on the default
 Windows PATH). The installer never edits your PATH. Once the directory is on
 PATH you run `apothem <command>` directly, with no manual `PYTHONPATH`. If the
-directory is not on PATH (or the shim could not be placed), the banner prints how
+directory is not on PATH (or the shim was not placed), the banner prints how
 to add it and falls back to the self-contained `PYTHONPATH=… python -m apothem`
 form — it never advertises a bare `apothem` command the run did not resolve.
 
@@ -294,25 +355,36 @@ and re-materialize.
 configuration (it prompts unless `--yes` / `-Yes`); pass `--remove-source` /
 `-RemoveSource` to also remove the managed clone at `APOTHEM_HOME`.
 
-Verify the install:
+**Verify:**
 
 ```shell
-npx @ahmed-g-gad/apothem verify --harness claude-code
+apothem verify --harness claude-code
 
-# or run the engine from the bundled source:
+# or, before the shim is on PATH, from the bundled source:
 PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code
 ```
 
-### VS Code family extension
+### 4 — VS Code family extension
+
+**Prerequisites:** VS Code, Node.js 18+, and system Python 3.10+ on `PATH`.
 
 Install the **Apothem** extension from the
-[Visual Studio Marketplace](https://marketplace.visualstudio.com/) — one
-extension covers VS Code and GitHub Copilot. Its commands (`Apothem:
+[Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ahmed-g-gad.apothem) —
+one extension covers VS Code and GitHub Copilot. Its commands (`Apothem:
 Install`, `Verify`, `Update`, `Uninstall`, `Doctor`) run the same engine
 through the configured runner (`npx @ahmed-g-gad/apothem` by default). Source
 lives under [`vscode-extension/`](vscode-extension/).
 
-### Gemini CLI extension
+**Verify:** run the **Apothem: Verify** command from the editor's command
+palette, or from a terminal:
+
+```shell
+npx @ahmed-g-gad/apothem verify --harness claude-code
+```
+
+### 5 — Gemini CLI extension
+
+**Prerequisites:** Gemini CLI, Node.js 18+, and system Python 3.10+ on `PATH`.
 
 Install Apothem as a Gemini CLI extension straight from the repository:
 
@@ -320,10 +392,24 @@ Install Apothem as a Gemini CLI extension straight from the repository:
 gemini extensions install https://github.com/ahmed-g-gad/apothem
 ```
 
-The extension loads an Apothem context file and adds a `/apothem` command that
-runs any engine subcommand.
+This extension is a bootstrap, not the full install on its own: it loads an
+Apothem context file and adds a `/apothem` command that shells out to the
+engine (`npx @ahmed-g-gad/apothem`). Materialize the full harness by running
+the install through it:
+
+```shell
+npx @ahmed-g-gad/apothem install --harness gemini-cli --project .
+```
+
+**Verify:**
 
-### Qwen Code extension
+```shell
+npx @ahmed-g-gad/apothem verify --harness gemini-cli --project .
+```
+
+### 6 — Qwen Code extension
+
+**Prerequisites:** Qwen Code, Node.js 18+, and system Python 3.10+ on `PATH`.
 
 Install Apothem as a Qwen Code extension straight from the repository:
 
@@ -331,11 +417,24 @@ Install Apothem as a Qwen Code extension straight from the repository:
 qwen extensions install ahmed-g-gad/apothem
 ```
 
-The extension loads an Apothem context file (`QWEN.md`). Qwen Code also installs
-Gemini CLI extensions and Claude Code marketplace plugins directly, so those
-entries work as well.
+Like the Gemini CLI extension, this is a bootstrap: it loads an Apothem context
+file (`QWEN.md`) and shells out to the engine; materialize the full harness by
+running the install through it. Qwen Code also installs Gemini CLI extensions
+and Claude Code marketplace plugins directly, so those entries work as well.
 
-### Codex plugin
+```shell
+npx @ahmed-g-gad/apothem install --harness qwen-code
+```
+
+**Verify:**
+
+```shell
+npx @ahmed-g-gad/apothem verify --harness qwen-code
+```
+
+### 7 — Codex plugin
+
+**Prerequisites:** Codex, Node.js 18+, and system Python 3.10+ on `PATH`.
 
 Add the repository as a Codex plugin marketplace, then install the plugin:
 
@@ -344,12 +443,46 @@ codex plugin marketplace add ahmed-g-gad/apothem
 codex plugin add apothem@apothem
 ```
 
-### OpenCode and other adapter-only tools
+Like the Gemini CLI and Qwen Code extensions, this is a bootstrap that shells
+out to the engine; materialize the full harness by running the install through
+it:
+
+```shell
+npx @ahmed-g-gad/apothem install --harness codex
+```
+
+**Verify:**
+
+```shell
+npx @ahmed-g-gad/apothem verify --harness codex
+```
+
+### 8 — Direct engine (`python -m apothem`)
+
+**Prerequisites:** system Python 3.10+ with the `click` and `rich` packages
+importable; a checkout of the repository. No Node.js required.
+
+Run the self-contained engine straight from a clone — the source tree carries
+its vendored dependencies, so `PYTHONPATH=src` is the whole setup:
+
+```shell
+git clone https://github.com/ahmed-g-gad/apothem
+cd apothem
+PYTHONPATH=src python -m apothem install --harness claude-code
+```
+
+**Verify:**
+
+```shell
+PYTHONPATH=src python -m apothem verify --harness claude-code
+```
+
+### Every other tool (OpenCode and adapter-only harnesses)
 
 Some tools — OpenCode among them — expose no separate plugin or extension
 registry for a configuration manager; their native surface is their own config
-directory. Apothem syncs those directly through the npm shim or the one-shot
-installers:
+directory. Apothem syncs those directly through the npm shim (channel 2), the
+one-shot installers (channel 3), or the direct engine (channel 8):
 
 ```shell
 npx @ahmed-g-gad/apothem install --harness opencode
@@ -387,7 +520,7 @@ graph LR
     A --> OC["~/.config/opencode/<br/>OpenCode"]
     A --> QW["~/.qwen/<br/>Qwen Code"]
     A --> TR["project .trae/rules<br/>Trae"]
-    A --> WI["project .devin/rules<br/>Windsurf (Devin Desktop)"]
+    A --> WI["project .devin/rules (.windsurf/rules fallback)<br/>Windsurf (Devin Desktop)"]
     A --> ZE["project .rules<br/>Zed"]
     A --> KM["project AGENTS.md + .kimi-code/<br/>Kimi Code"]
     A --> GL["project .apothem/providers/glm.toml<br/>GLM (Z.ai)"]

package/bin/apothem.mjs

@@ -19,9 +19,21 @@ const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const vendorPath = join(packageRoot, "src", "apothem", "_vendor");
 const sourcePath = join(packageRoot, "src");
 
+// The probe both enforces the version floor and rejects the Microsoft Store
+// launcher shims (zero-byte stubs under AppData\Local\Microsoft\WindowsApps).
+// Those stubs satisfy `python`/`py` on PATH but, when executed, open the Store
+// install page instead of running Python — every other entry path (install.sh
+// via hooks/lib/find-python.sh, install.ps1) already rejects them. `sys.base_prefix`
+// is printed so a real interpreter can be distinguished from a shim by path.
 const versionProbe =
-  "import sys; raise SystemExit(0 if sys.version_info[:2] >= " +
-  `(${MIN_PYTHON[0]}, ${MIN_PYTHON[1]}) else 1)`;
+  "import sys; " +
+  `sys.exit(1) if sys.version_info[:2] < (${MIN_PYTHON[0]}, ${MIN_PYTHON[1]}) else ` +
+  "print(sys.executable or '')";
+
+/** True when a resolved interpreter path is a Microsoft Store launcher shim. */
+function isWindowsAppsShim(execPath) {
+  return /[\\/]Microsoft[\\/]WindowsApps[\\/]/i.test(execPath);
+}
 
 /** Interpreter candidates, ordered; each is [command, ...leading args]. */
 const candidates = [];
@@ -33,9 +45,15 @@ candidates.push(["python3"], ["python"], ["py", "-3"]);
 function probe(candidate) {
   const [command, ...lead] = candidate;
   const result = spawnSync(command, [...lead, "-c", versionProbe], {
-    stdio: "ignore",
+    encoding: "utf8",
   });
-  return result.status === 0;
+  if (result.status !== 0) {
+    return false;
+  }
+  // Reject the Store shim: it can exit 0 on the probe yet trigger a Store
+  // popup (or fail) on the real invocation.
+  const execPath = (result.stdout || "").trim();
+  return !isWindowsAppsShim(execPath);
 }
 
 const interpreter = candidates.find(probe);
@@ -75,4 +93,20 @@ const run = spawnSync(command, [...lead, "-m", "apothem", ...process.argv.slice(
   stdio: "inherit",
   env,
 });
+
+// A spawn-level failure (ENOENT: interpreter vanished between probe and run;
+// EPERM: not executable) leaves `run.status` null with the cause in `run.error`
+// — report it instead of exiting a bare 1. A signal termination likewise leaves
+// `status` null; surface the signal so a killed child is not mistaken for a
+// clean exit.
+if (run.error) {
+  process.stderr.write(
+    `apothem: failed to run '${command}': ${run.error.message}\n`,
+  );
+  process.exit(1);
+}
+if (run.signal) {
+  process.stderr.write(`apothem: interpreter terminated by signal ${run.signal}\n`);
+  process.exit(1);
+}
 process.exit(run.status ?? 1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ahmed-g-gad/apothem",
-  "version": "0.1.1",
-  "description": "Host-agnostic AI-harness configuration manager: one shared profile materializes native configs for seventeen AI assistant harnesses, syncing rules, skills, slash-commands, hooks, and MCP servers behind a conformity governance gate and signed releases.",
+  "version": "1.0.0",
+  "description": "Host-agnostic AI-harness configuration manager: one shared profile materializes native configs for seventeen AI assistant harnesses, syncing rules, slash-commands, skills, hooks, output-styles, settings, schemas, and docs behind a conformity governance gate and signed releases.",
   "keywords": [
     "agent",
     "agnostic",
@@ -59,6 +59,12 @@
   "files": [
     "bin/",
     "src/apothem/",
+    "!**/__pycache__",
+    "!**/*.pyc",
+    "!**/*.pyo",
+    "!**/.mypy_cache",
+    "!**/.pytest_cache",
+    "!**/.ruff_cache",
     "pyproject.toml",
     "LICENSE",
     "LICENSES/",

package/pyproject.toml

@@ -1,12 +1,14 @@
 # SPDX-License-Identifier: MIT
 
 [build-system]
-requires      = ["setuptools>=68.0", "wheel"]
+# Modern setuptools builds wheels natively; a separate "wheel" requirement is
+# no longer part of the recommended configuration on packaging.python.org.
+requires      = ["setuptools>=77.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "apothem"
-version = "0.1.1"
+version = "1.0.0"
 description = "Host-agnostic AI-harness configuration manager: one shared profile materializes native configs for seventeen AI assistant harnesses, syncing rules, skills, slash-commands, hooks, and MCP servers behind a conformity governance gate and signed releases."
 requires-python = ">=3.10"
 readme = "README.md"
@@ -59,11 +61,11 @@ Homepage      = "https://apothem.ahmedgad.com/"
 Documentation = "https://apothem.ahmedgad.com/docs/usage/"
 Reference     = "https://apothem.ahmedgad.com/docs/reference/"
 Architecture  = "https://apothem.ahmedgad.com/docs/architecture/"
-Repository    = "https://github.com/ahmed-g-gad/apothem"
-Issues        = "https://github.com/ahmed-g-gad/apothem/issues"
-Discussions   = "https://github.com/ahmed-g-gad/apothem/discussions"
-Changelog     = "https://github.com/ahmed-g-gad/apothem/blob/main/CHANGELOG.md"
-Security      = "https://github.com/ahmed-g-gad/apothem/security"
+Repository    = "https://github.com/Ahmed-G-Gad/apothem"
+Issues        = "https://github.com/Ahmed-G-Gad/apothem/issues"
+Discussions   = "https://github.com/Ahmed-G-Gad/apothem/discussions"
+Changelog     = "https://github.com/Ahmed-G-Gad/apothem/blob/main/CHANGELOG.md"
+Security      = "https://github.com/Ahmed-G-Gad/apothem/security"
 Brand         = "https://apothem.ahmedgad.com/docs/brand/"
 
 # Console scripts are intentionally absent: apothem installs as a per-harness
@@ -176,18 +178,24 @@ where = ["src"]
 
 [project.optional-dependencies]
 dev = [
-    "ruff>=0.15.14",
+    # Floor at 0.15.20: 0.15.17 introduced (and 0.15.20 removed) rule RUF076,
+    # so pinning past the removal keeps selector behavior stable across
+    # contributor environments.
+    "ruff>=0.15.20",
     "mypy>=2.1.0",
     "types-PyYAML>=6.0.12.20260518",
     "types-jsonschema>=4.26.0.20260518",
-    "pytest>=9.0.3",
+    "pytest>=9.1.1",
     "pytest-cov>=7.1.0",
     "pytest-xdist>=3.8.0",
     # Hypothesis ratifies the property-test surface that feeds the OpenSSF
     # Scorecard Fuzzing check. Property tests at tests/property/ exercise
     # invariants (round-trip, idempotence, schema-validity) across
     # auto-generated inputs across the search space.
-    "hypothesis>=6.152.9",
+    # Floor below 6.156.0: that release begins the Rust-internals migration
+    # (native wheels; source builds need a Rust toolchain). Verify wheel
+    # coverage for every CI OS/arch target before floating past it.
+    "hypothesis>=6.155.7",
 ]
 security = [
     "bandit[toml]>=1.9.4",
@@ -264,13 +272,15 @@ ignore = ["E501"]
 # in the fixture's pass/fail counterparts, not authored in
 # real source.
 "tests/conformity/**" = ["E722", "S105", "S110", "F841", "BLE001"]
-# The hook dispatcher and emit_hook_context.py manipulate sys.path
-# before importing local helpers, so import-sort and module-import-
-# at-top rules cannot apply uniformly. The fail-open try/except/pass
-# is intentional per the dispatcher's contract: hook context is
-# advisory and must never block the underlying tool call.
-"src/apothem/hooks/dispatch.py"          = ["E402", "I001", "S110"]
-"src/apothem/hooks/emit_hook_context.py" = ["E402", "I001"]
+# The hook entrypoints (dispatch.py, emit_hook_context.py, and
+# session_start_bootstrap.py) manipulate sys.path before importing
+# local helpers, so import-sort and module-import-at-top rules cannot
+# apply uniformly. The fail-open try/except/pass (S110) is intentional
+# per the dispatcher's contract: hook context is advisory and must
+# never block the underlying tool call.
+"src/apothem/hooks/dispatch.py"                = ["E402", "I001", "S110"]
+"src/apothem/hooks/emit_hook_context.py"       = ["E402", "I001"]
+"src/apothem/hooks/session_start_bootstrap.py" = ["E402", "I001"]
 # Tooling scripts invoke subprocesses with controlled, internally-
 # constructed argument vectors. The S603 / S607 security rules
 # generalize to "untrusted input" but the inputs here are always

package/src/apothem/__main__.py

@@ -25,4 +25,10 @@ if __name__ == "__main__":
     # pipe or redirect. The group-callback call remains as defense-in-depth
     # for a direct ``apothem.cli.main`` import that bypasses this entry.
     _configure_stdio()
-    raise SystemExit(main())
+    # Pin the completion trigger. Click derives the completion env var from
+    # the detected program name, which under ``python -m apothem`` is
+    # "python -m apothem" — an unmatchable variable name — so the emitted
+    # completion scripts (which all set ``_APOTHEM_COMPLETE``) would never
+    # engage. Pinning complete_var keeps shell completion working on every
+    # invocation surface without altering usage strings.
+    raise SystemExit(main(complete_var="_APOTHEM_COMPLETE"))

package/src/apothem/_vendor/vendor.txt

@@ -19,4 +19,8 @@ jsonschema-specifications==2025.9.1
 referencing==0.37.0
 typing_extensions==4.15.0
 PyYAML==6.0.3
+# rpds-py: upstream moved to CalVer after 0.x; 0.30.0 was the final 0.x
+# release and is the intentionally-frozen API anchor the apothem-authored
+# pure-Python rpds shim mirrors. Do not bump this pin to a CalVer tag — the
+# shim tracks the 0.30.0 API subset, not the upstream distribution.
 rpds-py==0.30.0  # upstream API anchor for the apothem-authored rpds shim

package/src/apothem/agents/dependency-auditor.md

@@ -4,7 +4,7 @@ version: "0.1.0"
 updated: "2026-06-23"
 description: "Read-only dependency-tree risk audit — flags unpinned, stale, duplicate, and known-vulnerable dependencies with manifest/lockfile evidence. Use when auditing supply-chain risk, before a release cut, after adding a dependency, or when a CVE/advisory lands. Detects the ecosystem via host-discovery: npm (package.json + package-lock/yarn/pnpm), pip (pyproject/requirements + lock), cargo (Cargo.toml + Cargo.lock), go (go.mod + go.sum). Runs npm audit / pip-audit / cargo audit / govulncheck and returns a risk-ranked table (known-vulnerable → unpinned → duplicate → stale) with per-row evidence; never widens a pin or escalates a scope — gaps surface as inquiry."
 tools: "Read, Glob, Grep, Bash"
-disallowedTools: "Write, Edit"
+disallowedTools: "Write, Edit, TodoWrite"
 maxTurns: 15
 # maxTurns rationale: 15 exceeds the 5–10 norm because a dependency audit reads the manifest and
 # lockfile, enumerates direct and transitive entries, and runs the host's audit tooling

package/src/apothem/agents/fact-checker.md

@@ -4,7 +4,7 @@ version: "0.1.0"
 updated: "2026-06-23"
 description: "Read-only adversarial claim verification — decompose input into atomic claims, seek ≥2 independent sources, attempt refutation, assign cited verdicts (supported / refuted / unverifiable) with quoted evidence and confidence. Use when a claim needs proof before it ships: a benchmark or statistic in docs/copy, a 'X is faster/safer than Y' assertion, a citation that names an RFC or spec, a release note, or any factual claim a reviewer would challenge. Routes external claims through WebSearch / WebFetch and repository claims through Read / Glob / Grep; defaults to refuted-or-unverifiable when evidence is insufficient, never a charitable supported."
 tools: "Read, Glob, Grep, WebSearch, WebFetch"
-disallowedTools: "Write, Edit"
+disallowedTools: "Write, Edit, TodoWrite"
 maxTurns: 15
 # maxTurns rationale: 15 exceeds the 5–10 norm because adversarial verification requires
 # sequential search → fetch → cross-reference chains per claim. Each claim needs ≥2 independent