@ahmed-g-gad/apothem 0.1.1

package/src/apothem/harnesses/trae/templates/apothem-rules.md

@@ -0,0 +1,37 @@
+---
+trigger: always_on
+description: "Apothem governance and convention surface for the Trae harness — applied every session to honour project-wide engineering discipline."
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Apothem — Trae Bootstrap
+
+This file is materialised by `apothem install --harness trae --project <path>` and lands at `<project>/.trae/rules/apothem-rules.md`, a dedicated Apothem rules file inside the current Trae project rules directory per https://docs.trae.ai/ide/rules. It sits alongside the operator-owned `project_rules.md` and `user_rules.md` anchors and never clobbers them.
+
+## What Apothem governs in this project
+
+Apothem propagates a shared governance and convention surface across every supported AI harness in this project's host environment. Inside Trae, the surface manifests as this `always_on` rule file:
+
+- **Rules** — engineering rules applied on every interaction (`trigger: always_on`). The full rule cohort lives at the apothem source repository under `src/apothem/rules/`; this Trae-facing anchor names the disciplines the operator may consult in detail.
+- **Skills, commands, agents** — reusable techniques, slash-style workflows, and persistent sub-agent definitions. Apothem's canonical-master cohort at the apothem source repository defines them; Trae does not auto-discover them as separate surfaces, so they manifest here as referenced discipline.
+- **MCP** — Trae's tool-server surface (`.trae/mcp.json`) is operator-authored, not apothem-managed.
+- **Skills directory** — Trae's skill surface (`.trae/skills/`) is operator-authored, not apothem-managed.
+
+## Engineering disciplines in force
+
+Apothem's foundational mandates apply uniformly across every harness, including Trae:
+
+- **Plans-Locality.** Plan-suite artefacts (PROGRESS.md, PLAN-NOTES.md, PHASE.md, REPORT.md) live under `<project>/.apothem/plans/{suite}/` — the sole canonical home; a legacy `<project>/.plans/` tree upgrades via `apothem migrate-workspace`. They never land in a global plans directory or any other global-ecosystem location.
+- **Authority hygiene.** Never fabricate identity, scope, security posture, or version-pin data. Surface ambiguity through a question instead of inventing a plausible-looking value.
+- **Definitiveness.** Hedging vocabulary (`maybe`, `might`, `usually`, `generally`, `typically`, `probably`) is eliminated where binding prescription is possible. Pre / post / failure conditions are stated on every contract.
+- **Production-ready discipline.** Every change ships in production-ready form — tests, docs, CHANGELOG entry, conformant commit message, CI green — in the same change-set.
+- **Plain-language.** Codebase artefacts and user-facing prose read as natural domain language with zero trace of internal planning structure.
+- **Human-only authorship.** Git commit messages, PR descriptions, branch names, and tag annotations carry human contributors only — never the underlying language model, runtime, IDE extension, or any automated tool as a co-author.
+- **Lean-context delegation.** Where the host provides delegated-worker dispatch, broad reads and heavy workloads route to a spawned worker by default so the main working context stays lean. The heavy parallel apparatus stays opt-in; routing delegable work away from the main thread is the standing posture once dispatch is available.
+- **Observe-decide-act discipline.** Tool use runs as a loop — observe the current state, decide the next move from what was observed, then act — never an edit before a read or a result asserted before a check. Independent reads and searches run together in one pass, not one per turn; the loop closes on a verifiable condition (a gate green, a read confirmed), never a fixed number of tries. Advisory, never an auto-applied behavior.
+- **Source accessibility.** When the authoritative source for a claim, convention, or version pin is closed, paywalled, login-gated, or otherwise unreachable, ask the operator for it in full rather than substituting a lower-trust open page. Trust outranks reachability.
+
+## Refreshing the file
+
+Re-run `apothem install --harness trae --project <this-project-root>` to overwrite this file with the latest apothem template. The operation is idempotent. `apothem uninstall --harness trae --project <this-project-root>` renames the file to a timestamped backup; `apothem verify --harness trae --project <this-project-root>` checks the file is present and non-empty.

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

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the trae harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+
+_HARNESS_NAME: str = "trae"
+
+
+def uninstall(output_path: Path, *, project: Path | None = None) -> None:
+    """Remove Apothem-managed Trae targets surgically.
+
+    The apothem-rules ``sentinel_merge`` anchor is cleaned by the shared driver,
+    which strips only Apothem's managed block (operator prose survives), deletes
+    an Apothem-only file, 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,
+        project_root=project or output_path.parents[2],
+    )

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

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

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

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

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

@@ -0,0 +1,91 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Windsurf Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Adapter source: `src/apothem/harnesses/windsurf/`
+- Evidence level: adapter-local projection; no vendor-native UI claim is made here.
+
+## Official Surface Refresh
+
+- Refreshed live 2026-06-25 against the current vendor documentation
+  (`docs.devin.ai`). The windsurf harness rebranded to **Devin Desktop**
+  (OTA rollout 2026-06-02); the docs authority host moved from
+  `docs.windsurf.com` to the first-party Devin host `docs.devin.ai`. No
+  immutable version pin is exposed (mutable docs site), so every captured
+  convention carries a no-immutable-source exception. The harness slug stays
+  `windsurf`.
+- **Write-target migration.** The vendor's current docs make
+  `<project>/.devin/rules/*.md` the **preferred** workspace-rules surface, which
+  **takes precedence** over the retained backward-compat fallback at
+  `<project>/.windsurf/rules/*.md`. The adapter migrated its canonical write
+  target to `<project>/.devin/rules/apothem-rules.md` so the merged rules file is
+  never silently shadowed by any `.devin/rules/` content the operator already
+  keeps. Evidence: vendor-doc-url
+  <https://docs.devin.ai/desktop/cascade/workspace-rules>; snapshot-id living
+  docs; snapshot-date 2026-06-25.
+- Config-root correction: the global config root is `~/.codeium/windsurf/`
+  (global rules, MCP, skills, memories), not `~/.windsurf/`. The workspace
+  directory carries both the preferred `.devin/` tree (rules, skills) and the
+  retained `.windsurf/` fallback tree.
+- MCP is now recognized: `~/.codeium/windsurf/mcp_config.json` (stdio / HTTP /
+  SSE / OAuth) is operator-owned; the adapter recognizes it but does not author
+  entries. `capabilities.yml` `mcp_servers` and the shared capability matrix were
+  refreshed accordingly.
+- Workspace rules are a `*.md` directory (12k char per file), not a single file;
+  `layered_context_surface` names the preferred `.devin/rules/*.md` directory
+  with the `.windsurf/rules/` backward-compat fallback noted.
+- Native skills are a documented vendor surface at
+  `.windsurf/skills/<name>/SKILL.md` (Markdown SKILL.md with YAML frontmatter
+  carrying `name` + `description`); workflows (`.windsurf/workflows/`) and a
+  `hooks.json` hook surface are also vendor-side. The adapter delivers only the
+  project rules file and authors none of those cohorts (deliberate rules-only
+  posture). The `hooks.json` surface is **unverified against current docs** —
+  it could not be confirmed in the current official `docs.devin.ai` documentation
+  and is carried as a tracked claim pending re-verification. Settings,
+  agent-dispatch, plugins, and status-lines remain undocumented as file surfaces.
+- Web-fetch / browser-retrieval (`web_fetch` = **yes**): the Cascade agent
+  ships Web Search + URL Read (page fetch/chunk) tools, forced via `@web` and
+  `@docs`, gated by the "Enable Web Search" admin setting — the backing dimension
+  for `rules/source-accessibility.md` step 1. Evidence: vendor-doc-url
+  <https://docs.devin.ai/desktop/cascade/web-search>; snapshot-id living docs;
+  snapshot-date 2026-06-25.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. Windsurf rule templates 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.
+
+## Plugin-alone Persistence
+
+Windsurf (Devin Desktop) exposes **no vendor plugin or extension install surface**
+that Apothem ships. The adapter is project-scope rules-only: it writes a single
+merged rules file at `<project>/.devin/rules/apothem-rules.md` (the preferred
+surface; `.windsurf/rules/` is the backward-compat fallback) and authors no other
+cohort. There is no standalone-installable bundle; every artifact requires the
+full `apothem install --harness windsurf --project <path>` engine run.
+
+| Artifact class | Persists standalone? | Mechanism / limit |
+|---|---|---|
+| Rules | No — requires `apothem install` | The merged `apothem-rules.md` (carrying the embedded behavioral mandates) is written only by the engine into the preferred `.devin/rules/` directory (`.windsurf/rules/` backward-compat fallback). Nothing persists before that run. |
+| Commands / Skills / Agents | No — platform limit | The vendor documents native skills (`.windsurf/skills/<name>/SKILL.md`), workflows, and an unverified `hooks.json` surface but no command/agent primitive Apothem targets; these cohorts are not materialized for this harness (deliberate rules-only posture). |
+| Hooks / MCP / Settings | No — operator-owned / platform limit | `~/.codeium/windsurf/mcp_config.json` (MCP) is operator-owned and the `hooks.json` surface is unverified against current docs; the adapter authors no entries. |
+
+Platform limit: Windsurf ships no marketplace/extension channel, so a
+plugin-alone story does not exist — the merged rules file via `apothem install`
+is the sole persistence surface.

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

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for windsurf — project-scope install.
+
+Materializes the apothem rules surface into the operator-supplied
+project root at ``<project>/.devin/rules/apothem-rules.md`` — the
+preferred workspace-rules surface per the vendor's current docs
+(https://docs.devin.ai/desktop/cascade/workspace-rules). The windsurf
+harness rebranded to Devin Desktop (OTA 2026-06-02); ``.devin/rules/``
+now TAKES PRECEDENCE over the retained backward-compat fallback at
+``.windsurf/rules/``, so Apothem writes the canonical target into
+``.devin/rules/`` to avoid being silently shadowed. The harness slug stays
+``windsurf``. The legacy single-file ``.windsurfrules`` user-scope target is
+excluded; Windsurf / Devin workflows and memories are out of apothem's adapter
+scope.
+
+The adapter opts into the project-scope contract via
+``requires_project = True``; the CLI rejects an install / update /
+uninstall / verify invocation that omits ``--project <path>``. Delegates
+install logic to :mod:`apothem.harnesses.windsurf.install`, which
+consumes the canonical propagation manifest at
+``src/apothem/lib/propagation-manifest.yaml``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared.wrapper_factories import make_project_scope_adapter
+from apothem.harnesses.windsurf.install import install as _install
+from apothem.harnesses.windsurf.install import plan as _plan
+from apothem.harnesses.windsurf.uninstall import uninstall as _uninstall
+from apothem.harnesses.windsurf.update import update as _update
+from apothem.harnesses.windsurf.verify import verify as _verify
+
+# Sentinel relative path used by ``output_path`` for display purposes
+# only. The real target is resolved per-install via
+# ``resolve_output_path(project)`` once the operator supplies
+# ``--project <path>``.
+_SENTINEL_RELATIVE: Path = Path(".devin") / "rules" / "apothem-rules.md"
+
+WindsurfAdapter = make_project_scope_adapter(
+    "windsurf",
+    error_label="windsurf",
+    relative_target=_SENTINEL_RELATIVE,
+    install_fn=_install,
+    plan_fn=_plan,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="WindsurfAdapter",
+)

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

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. Windsurf
+# ratifies MCP via ~/.codeium/windsurf/mcp_config.json (operator-owned;
+# the adapter recognizes it but does not author entries). The windsurf
+# harness rebranded to Devin Desktop (OTA 2026-06-02); the adapter delivers a
+# single project rules file under the preferred .devin/rules/ surface (which
+# takes precedence over the .windsurf/rules/ backward-compat fallback) and does
+# not dispatch sub-agents or author workflow/skill/hook cohorts.
+
+mcp_servers:
+  - user-scope-~/.codeium/windsurf/mcp_config.json
+# Operator-owned MCP surface: the adapter recognizes it but authors no entries.
+mcp_servers_authored: false
+sub_agent_dispatch: false
+custom_command_support: "no"
+recommended_postfix_rendering: "plain-text"
+long_context_compaction: "profile-managed"
+context_ignore_surface: "not-documented-in-current-pin"
+layered_context_surface: ".devin/rules/*.md directory (preferred; .windsurf/rules/ backward-compat fallback)"
+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: Windsurf's Cascade agent ships Web Search
+# + URL Read (page fetch/chunk) tools, forced via `@web` and `@docs`, gated by
+# the "Enable Web Search" admin setting. Evidence triple — vendor-doc-url:
+# https://docs.windsurf.com/windsurf/cascade/web-search (307-redirects to the
+# Devin-branded first-party host docs.devin.ai post-acquisition; both first-party);
+# snapshot-id: living docs; 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.
+web_fetch: "yes"
+tool_surface_restrictions:
+  - secrets-paths
+  - destructive-shell-ops
+  - network-write-unsigned
+system_prompt_template_path: "templates/apothem-rules.md"
+agent_memory_surface: "n/a"

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

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the windsurf harness adapter.
+
+Materializes the apothem Windsurf rules surface into the operator-supplied
+project root. The windsurf harness rebranded to Devin Desktop (OTA
+2026-06-02); its preferred workspace-rules surface is now the project-scope
+multi-file format at ``<project>/.devin/rules/*.md`` (per
+https://docs.devin.ai/desktop/cascade/workspace-rules), which TAKES
+PRECEDENCE over the retained backward-compat fallback at
+``<project>/.windsurf/rules/*.md``. Apothem writes the canonical target into
+``.devin/rules/`` to avoid being silently shadowed. The harness slug stays
+``windsurf``. The legacy single-file ``.windsurfrules`` target is excluded.
+
+The propagation contract is declared in the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml`` under the ``windsurf`` key
+(a single ``sentinel_merge`` operation targeting
+``${PROJECT_ROOT}/.devin/rules/apothem-rules.md``) and applied by the
+shared driver at ``apothem.harnesses._shared.install_driver``. The
+``${PROJECT_ROOT}`` placeholder is substituted with the operator-supplied
+``--project <path>`` value the CLI threads through; absence of
+``--project`` is rejected upstream at ``apothem.cli._materialize`` via the
+``requires_project`` opt-in.
+"""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import (
+    make_project_scope_install,
+    make_project_scope_plan,
+)
+
+# Manifest harness key for this adapter.
+_HARNESS_NAME: str = "windsurf"
+
+install = make_project_scope_install(
+    _HARNESS_NAME,
+    error_message="windsurf adapter requires --project <path>; CLI must thread it through",
+)
+
+plan = make_project_scope_plan(_HARNESS_NAME)

package/src/apothem/harnesses/windsurf/templates/apothem-rules.md

@@ -0,0 +1,37 @@
+---
+trigger: always_on
+description: "Apothem governance and convention surface for the Windsurf harness — applied every session to honour project-wide engineering discipline."
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Apothem — Windsurf Bootstrap
+
+This file is materialised by `apothem install --harness windsurf --project <path>` and lands at `<project>/.devin/rules/apothem-rules.md`, the preferred workspace-rules surface per the vendor's current docs (https://docs.devin.ai/desktop/cascade/workspace-rules). The windsurf harness rebranded to Devin Desktop (OTA 2026-06-02); `.devin/rules/` now takes precedence over the retained backward-compat fallback at `.windsurf/rules/`. The legacy single-file `.windsurfrules` target is excluded because Apothem targets the multi-file project rules directory.
+
+## What Apothem governs in this project
+
+Apothem propagates a shared governance and convention surface across every supported AI harness in this project's host environment. Inside Windsurf, the surface manifests as this `always_on` rule file:
+
+- **Rules** — engineering rules applied on every interaction (`trigger: always_on`). The full rule cohort lives at the apothem source repository under `src/apothem/rules/`; this Windsurf-facing anchor names the disciplines the operator may consult in detail.
+- **Skills, commands, agents** — reusable techniques, slash-style workflows, and persistent sub-agent definitions. Apothem's canonical-master cohort at the apothem source repository defines them; Windsurf does not auto-discover them as separate surfaces, so they manifest here as referenced discipline.
+- **Workflows** — Windsurf's slash-command surface (`.windsurf/workflows/`) is operator-authored, not apothem-managed.
+- **Memories** — Windsurf's memory surface (`~/.codeium/windsurf/memories/`) is machine-local, not apothem-managed.
+
+## Engineering disciplines in force
+
+Apothem's foundational mandates apply uniformly across every harness, including Windsurf:
+
+- **Plans-Locality.** Plan-suite artefacts (PROGRESS.md, PLAN-NOTES.md, PHASE.md, REPORT.md) live under `<project>/.apothem/plans/{suite}/` — the sole canonical home; a legacy `<project>/.plans/` tree upgrades via `apothem migrate-workspace`. They never land in a global plans directory or any other global-ecosystem location.
+- **Authority hygiene.** Never fabricate identity, scope, security posture, or version-pin data. Surface ambiguity through a question instead of inventing a plausible-looking value.
+- **Definitiveness.** Hedging vocabulary (`maybe`, `might`, `usually`, `generally`, `typically`, `probably`) is eliminated where binding prescription is possible. Pre / post / failure conditions are stated on every contract.
+- **Production-ready discipline.** Every change ships in production-ready form — tests, docs, CHANGELOG entry, conformant commit message, CI green — in the same change-set.
+- **Plain-language.** Codebase artefacts and user-facing prose read as natural domain language with zero trace of internal planning structure.
+- **Human-only authorship.** Git commit messages, PR descriptions, branch names, and tag annotations carry human contributors only — never the underlying language model, runtime, IDE extension, or any automated tool as a co-author.
+- **Lean-context delegation.** Where the host provides delegated-worker dispatch, broad reads and heavy workloads route to a spawned worker by default so the main working context stays lean. The heavy parallel apparatus stays opt-in; routing delegable work away from the main thread is the standing posture once dispatch is available.
+- **Observe-decide-act discipline.** Tool use runs as a loop — observe the current state, decide the next move from what was observed, then act — never an edit before a read or a result asserted before a check. Independent reads and searches run together in one pass, not one per turn; the loop closes on a verifiable condition (a gate green, a read confirmed), never a fixed number of tries. Advisory, never an auto-applied behavior.
+- **Source accessibility.** When the authoritative source for a claim, convention, or version pin is closed, paywalled, login-gated, or otherwise unreachable, ask the operator for it in full rather than substituting a lower-trust open page. Trust outranks reachability.
+
+## Refreshing the file
+
+Re-run `apothem install --harness windsurf --project <this-project-root>` to overwrite this file with the latest apothem template. The operation is idempotent. `apothem uninstall --harness windsurf --project <this-project-root>` renames the file to a timestamped backup; `apothem verify --harness windsurf --project <this-project-root>` checks the file is present and non-empty.

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

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the windsurf harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+
+_HARNESS_NAME: str = "windsurf"
+
+
+def uninstall(output_path: Path, *, project: Path | None = None) -> None:
+    """Remove Apothem-managed Windsurf targets surgically.
+
+    The apothem-rules ``sentinel_merge`` anchor is cleaned by the shared driver,
+    which strips only Apothem's managed block (operator prose survives), deletes
+    an Apothem-only file, 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,
+        project_root=project or output_path.parents[2],
+    )

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

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

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

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

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

@@ -0,0 +1,92 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Zed Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Adapter source: `src/apothem/harnesses/zed/`
+- Evidence level: adapter-local projection; no vendor-native UI claim is made here.
+- canonical-filename: `.rules`
+- vendor-doc-url: https://zed.dev/docs/ai/instructions
+
+## Official Surface Refresh
+
+- Captured 2026-06-25 against the current Zed documentation (`zed.dev/docs`).
+  No authority-host move; no immutable version pin is exposed (mutable docs
+  site), so every captured convention carries a no-immutable-source exception.
+- Zed reorganized its AI docs (Reusable Rules → Skills, Always-on Rules →
+  Instructions, ~v1.4.0): `zed.dev/docs/ai/instructions`, `.../ai/skills`, and
+  `.../ai/rules` now coexist (the `ai/rules` page still resolves and documents
+  `.rules` / `.cursorrules` / `CLAUDE.md` / `AGENTS.md`). The `.rules`
+  project-root file behavior is unchanged and current — Zed still auto-includes
+  the flat `.rules` file as agent instructions; only the docs were reorganized
+  (re-verified live 2026-06-25 against `zed.dev/docs`).
+- Surface: Zed auto-includes a single flat project-root file `.rules` as agent
+  instructions (alongside the `AGENTS.md` / `CLAUDE.md` family). The format is
+  free-form plaintext / Markdown with no schema. The global surface is
+  `~/.config/zed/AGENTS.md`.
+- DIVERGENCE (flat file, no dedicated apothem file): unlike the cohort's
+  rules-directory shape (a dedicated `apothem-rules.md` inside a `rules/`
+  directory), Zed reads one flat `.rules` file at the project root. The adapter
+  therefore writes `<project>/.rules` directly. There is no per-tool rules
+  subdirectory to scope the apothem block into.
+- DIVERGENCE (backup-on-replace): because `.rules` is a single shared file an
+  operator may already maintain, the shared install driver backs up any
+  pre-existing `.rules` to a timestamped copy under `~/.apothem/backups/`
+  before replacement (and `apothem uninstall` renames the live file to a
+  timestamped sibling backup). The operator's prior instruction file is never
+  silently lost.
+- MCP is recognized: Zed's context servers are configured via
+  `.zed/settings.json` (and global settings) under `context_servers`
+  (operator-owned). The adapter recognizes the surface but does not author
+  entries. `capabilities.yml` `mcp_servers` and the shared capability matrix
+  reflect this.
+- The vendor documents threads, agent profiles, and MCP context servers as
+  separate surfaces. The adapter delivers only the project `.rules` file and
+  authors none of those cohorts (deliberate rules-only posture). Sub-agent
+  dispatch, hooks, skills, and output-styles remain undocumented as
+  adapter-owned file surfaces.
+- Skills (`discovery-pending`): Zed now documents a native Skills surface at
+  `zed.dev/docs/ai/skills` (the Reusable Rules → Skills migration). The adapter
+  does not yet author skill files for this harness; the surface is recognized
+  but its adapter-owned shape is discovery-pending against a pinned snapshot.
+  No absence is asserted — the surface exists and awaits a discovery pass.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. Zed instruction files 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`; Zed reads a single flat `.rules` file, so no vendor-native rule hierarchy is claimed beyond that file and 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.
+
+## Plugin-alone Persistence
+
+Zed exposes **no vendor plugin or extension install surface** that Apothem ships
+for its instruction surface. The adapter is project-scope rules-only: it writes a
+single flat merged file at `<project>/.rules` (backing up any pre-existing
+`.rules` first) and authors no other cohort. There is no standalone-installable
+bundle; every artifact requires the full
+`apothem install --harness zed --project <path>` engine run.
+
+| Artifact class | Persists standalone? | Mechanism / limit |
+|---|---|---|
+| Rules (flat `.rules`) | No — requires `apothem install` | The merged `.rules` file (carrying the embedded behavioral mandates) is written only by the engine to the project root. Nothing persists before that run. |
+| Commands / Skills / Agents | No — platform limit | Zed documents threads, agent profiles, and MCP context servers but no command/skill/agent file primitive Apothem targets; these cohorts are not materialized for this harness. |
+| Hooks / MCP / Settings | No — operator-owned / platform limit | `context_servers` in `.zed/settings.json` (MCP) is operator-owned; the adapter authors no entries. |
+
+Platform limit: Zed's editor extensions are language/theme plugins, not an
+instruction-cohort channel; a plugin-alone story does not exist for the
+governance surface — the merged `.rules` file via `apothem install` is the sole
+persistence surface.

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

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for zed — project-scope install.
+
+Materializes the apothem rules surface into the operator-supplied
+project root at ``<project>/.rules`` — the canonical Zed project
+agent-instruction file per https://zed.dev/docs/ai/instructions. Zed diverges
+from the cohort's rules-directory shape: it auto-includes a single flat
+project-root file (``.rules``, alongside the ``AGENTS.md`` / ``CLAUDE.md``
+family) as agent instructions, with no dedicated per-tool rules
+subdirectory. The adapter therefore writes a flat ``.rules`` file rather
+than a dedicated ``apothem-rules.md`` inside a rules directory. The
+global ``~/.config/zed/AGENTS.md`` surface and Zed's MCP context-server
+block (``.zed/settings.json`` ``context_servers``) are out of apothem's
+adapter scope.
+
+The shared install driver backs up any pre-existing ``.rules`` file
+before replace (timestamped copy under ``~/.apothem/backups/``), so an
+operator's existing instruction file is preserved.
+
+The adapter opts into the project-scope contract via
+``requires_project = True``; the CLI rejects an install / update /
+uninstall / verify invocation that omits ``--project <path>``. Delegates
+install logic to :mod:`apothem.harnesses.zed.install`, which consumes the
+canonical propagation manifest at
+``src/apothem/lib/propagation-manifest.yaml``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared.wrapper_factories import make_project_scope_adapter
+from apothem.harnesses.zed.install import install as _install
+from apothem.harnesses.zed.install import plan as _plan
+from apothem.harnesses.zed.uninstall import uninstall as _uninstall
+from apothem.harnesses.zed.update import update as _update
+from apothem.harnesses.zed.verify import verify as _verify
+
+# Sentinel relative path used by ``output_path`` for display purposes
+# only. The real target is resolved per-install via
+# ``resolve_output_path(project)`` once the operator supplies
+# ``--project <path>``. Zed's flat-file divergence: the sentinel is the
+# bare dotfile ``.rules`` at the project root, not a nested rules file.
+_SENTINEL_RELATIVE: Path = Path(".rules")
+
+ZedAdapter = make_project_scope_adapter(
+    "zed",
+    error_label="zed",
+    relative_target=_SENTINEL_RELATIVE,
+    install_fn=_install,
+    plan_fn=_plan,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="ZedAdapter",
+)

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

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. Zed ratifies
+# MCP context servers via .zed/settings.json (and global settings)
+# `context_servers` (operator-owned; the adapter recognizes it but does
+# not author entries). DIVERGENCE: Zed reads a single flat project-root
+# `.rules` file (alongside the AGENTS.md / CLAUDE.md family) as agent
+# instructions — not a dedicated Apothem file inside a rules directory.
+# The adapter writes that flat `.rules` file, backing up any pre-existing
+# `.rules` before replace, and does not dispatch sub-agents or author
+# workflow/skill/hook cohorts.
+
+mcp_servers:
+  - project-scope-.zed/settings.json#context_servers
+# Operator-owned MCP surface: the adapter recognizes it but authors no entries.
+mcp_servers_authored: false
+sub_agent_dispatch: false
+custom_command_support: "no"
+recommended_postfix_rendering: "plain-text"
+long_context_compaction: "profile-managed"
+context_ignore_surface: "not-documented-in-current-pin"
+layered_context_surface: "project-root .rules flat file (no rules directory)"
+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"). The pinned snapshot catalogs config-materialization
+# surfaces, not the vendor tool surface, so the web-fetch tool is not yet
+# discovered against the pin — discovery-pending per
+# rules/agent-capability-discipline-matrix.md §1.
+web_fetch: "discovery-pending"
+tool_surface_restrictions:
+  - secrets-paths
+  - destructive-shell-ops
+  - network-write-unsigned
+system_prompt_template_path: "templates/apothem-rules.md"
+agent_memory_surface: "n/a"

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

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the zed harness adapter.
+
+Materializes the apothem Zed rules surface into the operator-supplied
+project root. Zed's canonical agent-instruction surface is a single flat
+project-root file at ``<project>/.rules`` (per
+https://zed.dev/docs/ai/instructions) — a divergence from the cohort's
+rules-directory shape: Zed auto-includes one flat ``.rules`` file
+(alongside the ``AGENTS.md`` / ``CLAUDE.md`` family) rather than a
+per-tool rules subdirectory. The global ``~/.config/zed/AGENTS.md``
+target is excluded because Apothem targets the current project surface.
+
+The propagation contract is declared in the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml`` under the ``zed`` key
+(a single ``sentinel_merge`` operation targeting
+``${PROJECT_ROOT}/.rules``) and applied by the shared driver at
+``apothem.harnesses._shared.install_driver``, which backs up any
+pre-existing ``.rules`` before replace. The ``${PROJECT_ROOT}``
+placeholder is substituted with the operator-supplied ``--project
+<path>`` value the CLI threads through; absence of ``--project`` is
+rejected upstream at ``apothem.cli._materialize`` via the
+``requires_project`` opt-in.
+"""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import (
+    make_project_scope_install,
+    make_project_scope_plan,
+)
+
+# Manifest harness key for this adapter.
+_HARNESS_NAME: str = "zed"
+
+install = make_project_scope_install(
+    _HARNESS_NAME,
+    error_message="zed adapter requires --project <path>; CLI must thread it through",
+)
+
+plan = make_project_scope_plan(_HARNESS_NAME)