@ahmed-g-gad/apothem 0.1.1

package/src/apothem/harnesses/antigravity/install.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the antigravity harness adapter.
+
+Installs the apothem convention surface into the Antigravity CLI harness
+target. Antigravity reads ``~/.gemini/GEMINI.md`` as global context and
+stores CLI customization under ``~/.gemini/antigravity-cli/``; Apothem
+installs a named plugin at
+``~/.gemini/antigravity-cli/plugins/apothem/`` for cohorts that should not
+collide with Gemini CLI project-local files.
+
+The adapter is user-scope: it propagates under the harness root resolved
+as ``output_path.parent`` (``~/.gemini/``). Its propagation contract is
+declared in the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml`` under the ``antigravity``
+key and applied by the shared driver at
+``apothem.harnesses._shared.install_driver``. Drift between the
+propagation contract and the on-disk install is impossible by
+construction: the manifest IS the contract.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from apothem.harnesses._shared import install_driver
+from apothem.harnesses._shared.install_driver import MaterializationRun
+
+# Manifest harness key for this adapter.
+_HARNESS_NAME: str = "antigravity"
+
+
+def install(output_path: Path, profile: dict[str, Any]) -> MaterializationRun:
+    """Install the apothem convention surface into the Antigravity harness.
+
+    The harness root is derived as ``output_path.parent`` — the
+    ``AntigravityAdapter`` resolves this to ``~/.gemini/``. The shared
+    ``profile`` is projected into the ``GEMINI.md`` instruction anchor as a
+    sentinel-delimited Apothem managed block (operator prose outside the
+    sentinels is preserved); the convention cohort dirs are raw template copies
+    and convention-dir flattening alongside it. All operations are
+    idempotent — re-running replaces previous content cleanly, eliminating
+    stale files from prior install layouts.
+    """
+    return install_driver.finalize_install(
+        install_driver.run_install(
+            _HARNESS_NAME, harness_root=output_path.parent, profile=profile
+        ),
+        root=output_path.parent,
+    )
+
+
+def plan(output_path: Path) -> list[dict[str, str]]:
+    """Return the propagation plan for the configured harness without writing.
+
+    Each entry carries ``source`` (resolved on-disk path), ``target``
+    (resolved absolute path under ``output_path.parent``), and ``mode``
+    (the per-entry propagation mode declared in the manifest). The plan is the manifest's
+    install list materialized against the active harness root — the same
+    sequence ``install`` would apply, in declaration order.
+    """
+    return install_driver.build_plan(_HARNESS_NAME, harness_root=output_path.parent)

package/src/apothem/harnesses/antigravity/templates/GEMINI.md

@@ -0,0 +1,40 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Apothem — Antigravity Bootstrap
+
+This file is the vendor-canonical instructions surface for Google
+Antigravity (`~/.gemini/GEMINI.md`). Antigravity CLI customization lives
+under `~/.gemini/antigravity-cli/`; Apothem installs its user-scope
+convention cohort as the `apothem` plugin under
+`~/.gemini/antigravity-cli/plugins/apothem/`.
+
+## Apothem Conventions
+
+The Apothem-managed cohorts are propagated to:
+
+- `~/.gemini/antigravity-cli/plugins/apothem/plugin.json` — plugin metadata.
+- `~/.gemini/antigravity-cli/plugins/apothem/skills/` — reusable techniques
+  plus slash-command prompts converted into skills.
+- `~/.gemini/antigravity-cli/plugins/apothem/rules/` — behavioral reference
+  rules.
+- `~/.gemini/antigravity-cli/plugins/apothem/agents/` — local agent
+  definitions normalized from Apothem agents.
+- `~/.gemini/antigravity-cli/plugins/apothem/apothem/templates/` — support
+  templates retained for prompts that cite reusable plan or audit assets.
+- `~/.gemini/antigravity-cli/plugins/apothem/apothem/hooks/` — hook support
+  material retained as reference content; Apothem does not register
+  Antigravity hook events until the adapter owns the schema translation.
+
+## Project-Scope Surface
+
+Project-specific instructions remain project-owned. This user-scope adapter
+does not write workspace files unless the operator invokes a project-scope
+harness adapter separately.
+
+## Operator Surface
+
+Operators may extend this file with project-specific instructions. The
+apothem install re-renders this template on every `apothem install
+--harness antigravity` invocation; persistent operator content belongs in
+project-scope `<workspace>/.agents/` or an operator-owned Antigravity plugin
+instead of this file.

package/src/apothem/harnesses/antigravity/templates/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "apothem",
+  "version": "0.1.0",
+  "description": "Apothem shared governance profile for Antigravity CLI."
+}

package/src/apothem/harnesses/antigravity/uninstall.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the antigravity harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+
+_HARNESS_NAME: str = "antigravity"
+
+
+def uninstall(output_path: Path) -> None:
+    """Remove Apothem-managed Antigravity targets surgically.
+
+    The GEMINI.md anchor is a ``sentinel_merge`` manifest target, so the shared
+    driver strips only Apothem's managed block (operator prose survives) and
+    backs the file up under the Apothem backup root — no whole-file ``.bak``
+    sibling is left beside the operator's file.
+    """
+    install_driver.run_uninstall(_HARNESS_NAME, harness_root=output_path.parent)

package/src/apothem/harnesses/antigravity/update.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: MIT
+
+"""Update logic for the antigravity harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_update
+from apothem.harnesses.antigravity.install import install
+
+update = make_update(install)

package/src/apothem/harnesses/antigravity/verify.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify logic for the antigravity harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_verify_harness_root
+
+_HARNESS_NAME: str = "antigravity"
+
+verify = make_verify_harness_root(_HARNESS_NAME)

package/src/apothem/harnesses/claude_code/STANDARD-CONVENTION-PIN.md

@@ -0,0 +1,65 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Claude Code Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Snapshot note: live re-verification against `code.claude.com` docs (hooks-guide, sdk-permissions) — the `code.claude.com` authority host, the `settings.json` hooks structure + permission tiers (allow / ask / deny, deny-first), and the hook-event taxonomy all confirmed current; no immutable pin (living MDX docs)
+- Adapter source: `src/apothem/harnesses/claude_code/`
+- Evidence level: adapter-local projection; no vendor-native UI claim is made here.
+- Authority host: `code.claude.com` — the prior `docs.anthropic.com` / `docs.claude.com` hosts 301-redirect here (confirmed live 2026-05-31). The adapter pins no doc URLs in code, so no in-code URL change is required.
+
+## MCP and Permissions Surface Projection
+
+- MCP: registered via `claude mcp add --scope local|project|user`. Storage is `~/.claude.json` (user/local scope) and project `.mcp.json` — **not** `settings.json` (confirmed live 2026-05-31; `settings.json` carries only managed allow/deny gates). Apothem authors no MCP server entries; the template `settings.json` carries no `mcpServers`.
+- Permissions: `settings.json` `permissions` carries three tiers — `allow`, `ask`, `deny` — evaluated deny → ask → allow, first match wins. The Apothem template uses the `allow` and `deny` tiers; the `ask` tier is available but unused by default.
+- Hook events: the vendor taxonomy has expanded to roughly 30 events. Apothem wires a current, valid subset — SessionStart, PreToolUse (Write/Edit/NotebookEdit/Bash matchers), PreCompact, PostCompact, Stop — all confirmed current 2026-05-31; no template change required.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. Claude Code-facing prompts and rule text preserve that suffix as authored.
+- Boundary: this pin does not claim a harness-native recommended-option widget. It only pins the text-rendered convention used by `rules/interactive-questions.md`.
+
+## Long Context and Compaction
+
+- Status: profile-managed.
+- Mechanism: Apothem keeps full-suite `/plan-execute` runs continuous by externalizing state to `.apothem/plans/`, compacting or restarting the harness session at phase boundaries as needed, and restoring via the Blind Bootstrap sequence.
+- Boundary: this pin does not claim vendor-native autocompaction or a long-context size. It pins the adapter-local state handoff and compaction-restoration convention used by `rules/context-management.md`.
+
+## Large-Codebase Practice Projection
+
+- Layered context: declared in `capabilities.yml` under `layered_context_surface`; no vendor-native hierarchy is claimed beyond the adapter's documented file/template surface.
+- LSP symbol navigation: `tracked-gap` until a vendor-ratified plugin or tool surface is pinned.
+- Hook learning capture: routed through the `persistent-conventions-vigilance` artifact-evolution cycle; pass-class hooks stay silent and recurring findings become rule, skill, hook, or documentation updates.
+
+## Web-Fetch / Browser-Retrieval Surface
+
+- Capability: `web_fetch` = **yes**. The backing dimension for `rules/source-accessibility.md` step 1 ("retrieve through the host's browser / fetch capability").
+- Vendor-confirmed: Claude Code ships built-in WebFetch and WebSearch tools (the CLI surface of the `web_fetch_*` / `web_search_*` server tools).
+- Evidence: vendor-doc-url <https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool> (the prior `docs.claude.com` path 302-redirects here); snapshot-id living MDX (no immutable commit; living-docs host); snapshot-date 2026-06-21.
+
+## Plugin-alone Persistence
+
+Claude Code is the one harness with a **full standalone plugin**:
+`.claude-plugin/plugin.json` (installed via
+`/plugin marketplace add ahmed-g-gad/apothem`) declares `commands`, `agents`,
+`skills`, and `hooks` (`./src/apothem/hooks/hooks.json`, resolved against
+`${CLAUDE_PLUGIN_ROOT}`). Installing the plugin *alone* — without running
+`apothem install` — persists most of the cohort directly.
+
+| Artifact class | Persists plugin-alone? | Mechanism / limit |
+|---|---|---|
+| Commands | Yes | The manifest `commands` array (46 entries — the 45 command files plus the `./commands/` default-directory entry) loads the 45 slash-commands from the plugin tree; the directory entry holds no `*.md` and loads no command — it addresses the Claude Code v2.1.140+ default-folder note so the explicit nested paths stay authoritative. |
+| Agents | Yes | The manifest `agents` array (12 entries) loads sub-agents from the plugin tree. |
+| Skills | Yes | The manifest `skills` reference loads the skill cohort from the plugin tree. |
+| Hooks | Yes | The manifest `hooks` field points at the bundled `hooks.json`, wired with `${CLAUDE_PLUGIN_ROOT}`-relative dispatch — the PreToolUse/SessionStart/etc. pipeline fires from the plugin alone. |
+| Rules | Degraded — requires `apothem install` for full reference tree | The plugin carries no rules-directory primitive; the embedded directives degrade to a SessionStart `additionalContext` pointer. The full `${HARNESS_ROOT}/rules/` reference tree lands only via the engine. |
+| Settings / output-styles / gate matchers | No — requires `apothem install` | `settings.json` (managed allow/deny + statusline), `output-styles/`, and the conformity `gate.py` + `schemas/` ride beside the engine install, not the plugin package. |
+| MCP | No — operator-owned | MCP servers register via `claude mcp add` into `~/.claude.json` / project `.mcp.json`; neither the plugin nor the engine authors entries. |
+
+Bundle status: this is the reference plugin-alone implementation — commands,
+agents, skills, and hooks persist from the plugin package directly; only the full
+rules reference tree, settings, output-styles, and the gate engine need
+`apothem install`.

package/src/apothem/harnesses/claude_code/__init__.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for claude-code — full-surface install.
+
+Writes the canonical ``settings.json`` template and flattens the convention
+dirs (agents/, commands/, rules/, skills/, statuslines/, output-styles/) at
+the harness root. The install is self-contained: the hook dispatcher and the
+conformity gate are materialized under the harness root (``apothem/hooks/``
+and ``apothem/conformity/`` with the sibling ``apothem/schemas/`` fixtures)
+and invoked by absolute path from ``settings.json``; no pip-installed
+package is required. No ``src/apothem/`` mirror is produced; flat-copied
+source trees found at the harness root are swept on every install per the
+propagation manifest's stale-sweep list. The shared profile is projected into
+``~/.claude/CLAUDE.md`` as a sentinel-delimited Apothem managed block — operator
+prose outside the sentinels is preserved verbatim — so the apothem governance
+surface reaches Claude Code through that managed block, the propagated ``rules/``
+tree, and the SessionStart hook. Delegates install logic to
+:mod:`apothem.harnesses.claude_code.install`.
+
+Plugin-alone capability
+-----------------------
+
+The Claude Code plugin can be installed alone via the marketplace, with no
+separate ``python -m apothem install`` engine install. In that posture the
+plugin's ``.claude-plugin/plugin.json`` ``hooks`` field points at a generated
+``hooks.json`` (see :func:`apothem.lib.plugin_tree.build_plugin_hooks_json`)
+whose every command drives the shell bootstrap stub under
+``${CLAUDE_PLUGIN_ROOT}``. The stub self-locates a CPython interpreter and
+execs the bundled dispatcher, so hooks fire without the engine install's
+``${PYTHON_BIN}`` / ``${HARNESS_ROOT}`` substitution. The honest capability
+split:
+
+* **Persists plugin-alone.** The SessionStart bootstrap (which now emits a
+  lean pointer to the bundled ``rules/`` plus a note that the mechanical hooks
+  are active), the PreToolUse write / edit / notebook / bash context guards
+  (authorship-header, plans-locality, base context nudges), and the
+  PreCompact / PostCompact / Stop handlers — every dispatch-routable hook event.
+* **Degrades plugin-alone.** The behavioral ``rules/`` are bundled under the
+  plugin root but cannot load as always-on context; they degrade to the
+  SessionStart pointer plus the still-active mechanical hooks. The conformity
+  gate's ``gate.py --hook`` entry is NOT wired plugin-alone — the bootstrap
+  stub drives only the dispatcher, and the gate's scope default targets a
+  harness root (``~/.claude`` / ``~/.codex``) rather than a plugin-alone
+  project write; full conformity-gate enforcement needs the engine install.
+* **Needs the engine install.** The materialized ``settings.json``
+  (permissions allow / deny floor), the ``output-styles/`` and
+  ``statuslines/`` cohorts, and the ``CLAUDE.md`` managed-block projection are
+  engine-install surfaces with no plugin manifest field.
+* **Not shipped today.** No MCP server is bundled, so no MCP tools surface
+  from the plugin alone.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from apothem.harnesses._shared.install_driver import MaterializationRun
+from apothem.harnesses.claude_code.install import install as _install
+from apothem.harnesses.claude_code.install import plan as _plan
+from apothem.harnesses.claude_code.uninstall import uninstall as _uninstall
+from apothem.harnesses.claude_code.update import update as _update
+from apothem.harnesses.claude_code.verify import verify as _verify
+
+
+class ClaudeCodeAdapter:
+    """ClaudeCodeAdapter — implements :class:`~apothem.harnesses.HarnessAdapter`."""
+
+    @property
+    def name(self) -> str:
+        """Return the canonical kebab-case harness identifier."""
+        return "claude-code"
+
+    @property
+    def output_path(self) -> Path:
+        """Return the always-propagated singleton config file path.
+
+        The adapter resolves the harness root as ``output_path.parent``;
+        ``is_installed()`` / ``verify()`` resolve against this file. The
+        always-written ``settings.json`` is the singleton presence anchor; the
+        profile-projected ``CLAUDE.md`` managed block is written alongside it.
+        """
+        return Path.home() / ".claude/settings.json"
+
+    def install(self, profile: dict[str, Any]) -> MaterializationRun:
+        """Materialize the harness configuration from the shared profile."""
+        return _install(self.output_path, profile)
+
+    def update(self, profile: dict[str, Any]) -> MaterializationRun:
+        """Re-materialize the harness configuration from the updated profile."""
+        return _update(self.output_path, profile)
+
+    def plan(self, output_path: Path | None = None) -> list[dict[str, str]]:
+        """Return the manifest-driven propagation plan without writing."""
+        return _plan(output_path or self.output_path)
+
+    def uninstall(self) -> None:
+        """Remove the harness configuration file if present."""
+        _uninstall(self.output_path)
+
+    def is_installed(self) -> bool:
+        """Return True if the configuration file exists on disk."""
+        return self.output_path.exists()
+
+    def verify(self) -> bool:
+        """Return True if the installed configuration is valid."""
+        return _verify(self.output_path)

package/src/apothem/harnesses/claude_code/capabilities.yml

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. The claude_code
+# harness ratifies every cohort capability: MCP via `claude mcp add` into
+# ~/.claude.json (user/local scope) + project-level .mcp.json — NOT
+# settings.json (confirmed live 2026-05-31); sub-agents in ~/.claude/agents/;
+# auto-memory at ~/.claude/projects/<project>/memory/; system-prompt projects
+# through CLAUDE.md (operator-owned; adapter does not manage). Apothem names
+# the native MCP surface but does not author MCP server entries.
+
+mcp_servers:
+  - claude.json-user-local-scope-via-claude-mcp-add
+  - project-level-.mcp.json
+# Operator-owned MCP surface: the adapter recognizes it but authors no entries.
+mcp_servers_authored: false
+sub_agent_dispatch: true
+custom_command_support: "yes"
+recommended_postfix_rendering: "plain-text"
+long_context_compaction: "profile-managed"
+context_ignore_surface: "settings.json permissions {allow, ask, deny}"
+layered_context_surface: "CLAUDE.md hierarchy plus propagated convention dirs"
+lsp_symbol_navigation: "tracked-gap-no-adapter-owned-LSP-surface"
+hook_learning_capture: "artifact-evolution-cycle"
+standard_convention_pin: "STANDARD-CONVENTION-PIN.md"
+# web-fetch / browser-retrieval surface — the backing capability dimension for
+# rules/source-accessibility.md step 1 ("retrieve through the host's browser /
+# fetch capability"). Vendor-confirmed: Claude Code ships built-in WebFetch and
+# WebSearch tools (the CLI surface of the `web_fetch_*` / `web_search_*` server
+# tools). Evidence triple — vendor-doc-url:
+# https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool
+# (the prior docs.claude.com path 302-redirects here); snapshot-id: living MDX
+# (no immutable commit; living-docs host); snapshot-date: 2026-06-21. Canonical
+# evidence home is STANDARD-CONVENTION-PIN.md per
+# rules/agent-capability-discipline-matrix.md §1A; pin refresh tracked as a
+# follow-up to fold this triple into the pin's evidence chain.
+web_fetch: "yes"
+tool_surface_restrictions:
+  - secrets-paths
+  - destructive-shell-ops
+  - network-write-unsigned
+system_prompt_template_path: "n/a"
+agent_memory_surface: "~/.claude/projects/<project>/memory/ (auto-memory) plus CLAUDE.md"

package/src/apothem/harnesses/claude_code/install.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the claude-code harness adapter.
+
+Installs the Apothem convention surface — not the Python library
+implementation — into the Claude Code harness target (``~/.claude/`` by
+default). The convention surface is the set of artifacts that match
+Claude Code's native discovery patterns (agents, commands, skills,
+rules, output-styles, statusline). Command prompts are also wrapped as
+skills so reusable workflows are visible through the current skill surface.
+The hook dispatcher, conformity gate, and
+their schema fixtures are materialized under the harness root
+(``apothem/hooks/``, ``apothem/conformity/``, ``apothem/schemas/``)
+so the settings.json hook entries invoke them by absolute script path
+— no importable ``apothem`` package is required on the host. Each hook
+entry's ``command`` carries a ``${PYTHON_BIN}`` placeholder the install
+resolves to the absolute path of a real CPython >= 3.10 (per
+``apothem.lib.python_resolver``) so no entry invokes a bare ``python``
+that a host PATH could resolve to a Microsoft Store WindowsApps launcher
+stub.
+
+The shared profile is projected into the user-scope ``CLAUDE.md`` instruction
+anchor as a sentinel-delimited Apothem managed block (identity / preferences /
+rules / seriousness / opted-in behaviors); operator prose outside the sentinels
+is preserved verbatim. Per the ratified transport map, Claude Code MCP is
+registered via ``claude mcp add`` into ``~/.claude.json`` / project ``.mcp.json``
+— not a file Apothem authors — so this adapter projects no MCP entries and the
+``settings.json`` permissions/hooks template is left unchanged.
+
+The adapter is user-scope: it propagates under the harness root resolved
+as ``output_path.parent`` (``~/.claude/``). Its propagation contract —
+the install list, exclude globs, stale-sweep entries, and per-directory
+filename filter — is declared in the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml`` under the ``claude_code``
+key and applied by the shared driver at
+``apothem.harnesses._shared.install_driver``. Drift between the
+propagation contract and the on-disk install is impossible by
+construction: the manifest IS the contract.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from apothem.harnesses._shared import install_driver
+from apothem.harnesses._shared.install_driver import (
+    MaterializationResult,
+    MaterializationRun,
+)
+from apothem.lib import atomic_io
+from apothem.lib.profile import coerce_profile
+from apothem.lib.profile_projection import project
+from apothem.lib.python_resolver import resolve_python_bin
+
+# Manifest harness key for this adapter.
+_HARNESS_NAME: str = "claude_code"
+# Public adapter id used to resolve per-harness profile overrides.
+_HARNESS_ID: str = "claude-code"
+# Placeholder the settings.json template carries on every hook ``command``
+# field; resolved to an absolute CPython path at install time so no hook
+# entry invokes a bare ``python`` (which a host PATH can resolve to a
+# Microsoft Store WindowsApps launcher stub).
+_PYTHON_BIN_TOKEN: str = "${PYTHON_BIN}"  # noqa: S105 — template placeholder token, not a secret
+
+
+def _resolve_hook_interpreter(harness_root: Path) -> list[MaterializationResult]:
+    """Substitute ``${PYTHON_BIN}`` in the installed settings.json.
+
+    Reads the settings.json the manifest install just wrote, replaces every
+    ``${PYTHON_BIN}`` placeholder with the absolute path to a real CPython
+    >= 3.10 resolved per :func:`resolve_python_bin`, and rewrites the file
+    in place. The rewrite is a pure token substitution on the file the same
+    install just produced, so it is written atomically *without* a
+    backup-before-replace and *without* the JSON key-merge — both would
+    corrupt the substitution (the merge re-prefers the existing
+    ``${PYTHON_BIN}`` token, and the backup would capture the un-resolved
+    intermediate state as a stray sibling). Idempotent: the resolved path is
+    stable across installs on the same host, so re-running yields
+    byte-identical output. A settings.json with no placeholder (already
+    resolved, or an operator-stripped hooks block) is left untouched.
+    """
+    settings_path = harness_root / "settings.json"
+    if not settings_path.is_file():
+        return []
+    content = settings_path.read_text(encoding="utf-8")
+    if _PYTHON_BIN_TOKEN not in content:
+        return []
+    python_bin = resolve_python_bin().as_posix()
+    rendered = content.replace(_PYTHON_BIN_TOKEN, python_bin)
+    if rendered == content:
+        return []
+    atomic_io.write_bytes_atomically(settings_path, rendered.encode("utf-8"))
+    return [
+        MaterializationResult(
+            outcome="updated",
+            operation="resolve-python-bin",
+            path=str(settings_path),
+            message=f"resolved hook interpreter to {python_bin}",
+            source=None,
+            backup_path=None,
+            detail={"python_bin": python_bin},
+        )
+    ]
+
+
+def install(output_path: Path, profile: dict[str, Any]) -> MaterializationRun:
+    """Install the apothem convention surface into the Claude Code harness.
+
+    The harness root is derived as ``output_path.parent`` — the
+    ``ClaudeCodeAdapter`` resolves this to ``~/.claude/``. The manifest-driven
+    convention surface (settings.json, agents/, commands→skills/, rules/,
+    skills/, support trees) is materialized first, then the shared *profile* is
+    projected into the user-scope ``CLAUDE.md`` instruction anchor as a
+    sentinel-delimited managed block (identity / preferences / rules /
+    seriousness / opted-in behaviors). Operator prose outside the sentinels is
+    preserved verbatim. All operations are idempotent — re-running with the same
+    profile yields byte-identical output and preserves unrelated
+    operator-authored discovery entries.
+    """
+    harness_root = output_path.parent
+    run = install_driver.run_install(_HARNESS_NAME, harness_root=harness_root)
+    for_harness = coerce_profile(profile).for_harness(_HARNESS_ID)
+    surfaces = project(for_harness, _HARNESS_ID)
+    anchor_result = install_driver.apply_managed_block_anchor(
+        harness_root / "CLAUDE.md",
+        surfaces.managed_block_body,
+        install_root=harness_root,
+        harness_name=_HARNESS_NAME,
+        allowed_root=harness_root.parent,
+    )
+    interpreter_results = _resolve_hook_interpreter(harness_root)
+    return install_driver.finalize_install(
+        run.extend([anchor_result, *interpreter_results]), root=harness_root
+    )
+
+
+def plan(output_path: Path) -> list[dict[str, str]]:
+    """Return the propagation plan for the configured harness without writing.
+
+    Each entry carries ``source`` (resolved on-disk path), ``target``
+    (resolved absolute path under ``output_path.parent``), and ``mode``
+    (``write_text``, a tree mode, or a conversion mode). The plan is the manifest's
+    install list materialized against the active harness root — the same
+    sequence ``install`` would apply, in declaration order.
+    """
+    return install_driver.build_plan(_HARNESS_NAME, harness_root=output_path.parent)