diff --git a/CLAUDE.md b/CLAUDE.md index c3de5c1..f26660e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,6 +16,8 @@ Four places. **Only this file is loaded into your context automatically** — th - **`blueprint/project-family.md`** — the design document and source of truth, referenced by section number (§0.1 neutrality, §2 threat model, §4/§5.1 crypto + database layout, §6 filesystem, §7 MCP, §9 unlock, §11 `UserManager`, §12 auth schema, §13 reports, §14/§15 connectors, §16 LLM privacy tiers, §17 sequencing, §19). **Gitignored and not under version control.** Read it before any architectural work, and never assume a section says what you remember. - **`docs/`** — *not* developer documentation: it is written for the in-app LLM and mounted read-only into every user's container. See [Documentation](#documentation). +Code that lives outside this repo but that a change here can break is listed under [Sibling repositories](#sibling-repositories). + **Before you touch one of these areas, open its file:** | You are touching | Read | @@ -35,6 +37,18 @@ Four places. **Only this file is loaded into your context automatically** — th A pointer is not a summary. If the table sends you to a file, that file is where the decision was recorded and why the obvious alternative was rejected — inferring it from this one instead is how a trap already paid for gets stepped on twice. +## Sibling repositories + +Three repositories are checked out **beside** this one, at the same level as its root. They are separate git repos — own history, own `CLAUDE.md`, own release cycle — and are not part of this Cargo workspace: + +| Path | What it is | It concerns you when | +| ---- | ---- | ---- | +| `../marketplace` | The **Skald Connectors Marketplace**: the connector feed and every manifest in it. Its `CONNECTOR_MANIFEST_GUIDE.md` is the **authoritative authoring spec**; this repo deliberately keeps no copy, because two files with one name drift and the one sitting next to the connectors is the one an author actually reads. | you touch the manifest format, the feed schema, or anything `mcp::install` consumes. The spec is edited **there**, never restated here. | +| `../skald-circle-ios` | The iOS client (Swift): a remote control for an instance — chat, projects, files, approvals — end-to-end encrypted. Pairs through `crates/plugin-mobile-connector`. | you change that plugin's wire protocol, pairing flow or push payloads. | +| `../skald-circle-android` | The Android client (Kotlin/Gradle), same role as the iOS one. **Early stage** — the repo exists but has no commits yet. | same as above. | + +**Do not edit them as a side effect of work done here.** The coupling that matters is `plugin-mobile-connector`: a shipped client cannot be recompiled by this repo's build, so a protocol change is a compatibility decision, not a refactor. When a change here breaks one of them, say so and let it get its own commit in its own repo. + ## What this repository is A **dedicated fork** of Skald, turning a single-user personal agent into a **multi-user assistant for a small trusted group** — positioned at families, but see the neutrality rule below. diff --git a/dev-docs/mcp-connectors.md b/dev-docs/mcp-connectors.md index a4800a6..08ed5f9 100644 --- a/dev-docs/mcp-connectors.md +++ b/dev-docs/mcp-connectors.md @@ -27,7 +27,7 @@ MCP servers are surfaced to users as **"Connectors"** (UI naming; `mcp`/schema s **The verify runs with `.pydeps` on `PYTHONPATH`, and must** (`mcp::verify::verify_env`). Only the *server* launch used to get that path (`global_row_spec` / `user_row_spec`); the verify is a bare `sh -c` inheriting nothing, so a python connector was rejected **by its own verify** for a dependency sitting installed one directory away — and `global_enable` installs *before* it verifies, so the deps were provably there at the moment the check denied them. The failure selected for well-written connectors: declaring no `verify` meant never meeting it. The workdir *is* the connector dir in both targets, so the path is derived, not plumbed, and set with `or_insert` — an explicit `PYTHONPATH` from the form is the author's. One gap left deliberately: `POST /api/mcp/test` (the Test button) shares `run_verify` but **not** `ensure_installed_host`, so testing a python connector that was never enabled on this box still fails on the missing deps. Making a "try it" button write to disk for minutes is the worse trade; enable first. -**The connector specs live in the marketplace repository, not here.** The feed and everything that authors for it are a separate repo, checked out at `~/projects/marketplace`, and the authoring contract is **`CONNECTOR_MANIFEST_GUIDE.md` at its root** — same filename this repo used to carry a copy of, which is exactly why the copy is gone: two files with one name drift, and the one next to the connectors is the one an author reads. **If the connector specification ever has to change, that is the file to consult and to edit** — nothing in this repo restates it. +**The connector specs live in the marketplace repository, not here.** The feed and everything that authors for it are a separate repo, checked out beside this one at `../marketplace`, and the authoring contract is **`CONNECTOR_MANIFEST_GUIDE.md` at its root** — same filename this repo used to carry a copy of, which is exactly why the copy is gone: two files with one name drift, and the one next to the connectors is the one an author reads. **If the connector specification ever has to change, that is the file to consult and to edit** — nothing in this repo restates it. **Connector versioning.** `mcp_catalog` carries `version` (INTEGER — the update-comparison key), `version_string` (semver, display) and `version_release_date` (ISO, display), snapshotted from the feed on install. The marketplace list computes `update_available` = feed `version` > installed `version` (strict) and surfaces it as an "Update" button (`marketplace.js`). The integer is the UI signal; the actual re-install trigger is the reconciler's content-hash.