@systemdox/mcp-server 0.1.45 → 0.1.47

package/README.md

@@ -140,6 +140,121 @@ npx -y @systemdox/mcp-server install-skill <name> [--version n] [--target dir] [
 Exit codes: `0` installed, `1` usage / no key / API error, `2` refused because
 files there were edited.
 
+### Team setup (ADR-217)
+
+Your workspace's Claude Code setup (hooks, MCP servers, agents, commands, the
+skills your team chose, and one team `CLAUDE.md`) is published to SystemDox and
+reaches every member's computer as one plugin, `<workspace>-setup`.
+
+- **`publish_setup_part`** (both servers) publishes one part: `hooks`
+  (`hooks/hooks.json` and the `scripts/` it calls), `mcp` (`.mcp.json`),
+  `agents` (`agents/*.md`), `commands` (`commands/*.md`) or `instructions`
+  (`CLAUDE.md`). On your own computer pass `directory`: only the files the part
+  accepts are read, and a link, a binary file or a file over the limits stops it
+  before anything is sent. Every part but `instructions` makes a new plugin
+  version, which each member accepts at their next update. For `mcp`, every
+  `env` and `headers` value is replaced by a `${NAME}` reference to each
+  member's own environment variable. Publishing `hooks`, `mcp`, `agents` or
+  `commands` needs the admin role (SYD-A003 otherwise).
+- **`resolve_person`** (both servers) reads back a person a team memory names
+  by identifier (`` `con_…` (reseller, sales) ``): their label, name, phone
+  number and email address. The details are for that session only; the memory
+  keeps the identifier. It writes nothing.
+- **`sync_memory`** (your own computer only) syncs a project's team memory, as
+  `sync-memory` below does with no one at the terminal: it never answers a
+  question about a person and never rewrites a file for one. A file that still
+  holds a phone number, an email address or a home-folder path is skipped and
+  listed with the command to run yourself. Inputs: `project`, `dryRun`.
+
+One command sets up your computer, and the same command updates it:
+
+```bash
+npx -y @systemdox/mcp-server setup [--project <name>] [--dir <checkout>] [--yes] [--overwrite]
+```
+
+- It first writes the SystemDox MCP server into your AI tool's config, as it
+  always has. Then, when your workspace has anything published, it checks that
+  Claude Code is 2.1.316 or later (`claude update` otherwise) and shows you
+  everything it will add: the marketplace entry for `~/.claude/settings.json`,
+  the plugin with every hook command and every MCP server's command or URL
+  verbatim, the import block for `~/.claude/CLAUDE.md`, each team memory with
+  its file count and folder, and the `autoMemoryDirectory` it will set. On an
+  update it shows only what changed, with a line diff for hooks and
+  instructions. Nothing changes until you answer `y`.
+- Then, in this order: your key goes into
+  `~/.claude/systemdox/credentials.json` (readable by you alone, and nowhere
+  else); the team instructions into `~/.claude/systemdox/<workspace>/CLAUDE.md`
+  (if you edited that file, it stops unless `--overwrite`); one marked import
+  block into `~/.claude/CLAUDE.md`; one `extraKnownMarketplaces` entry,
+  `systemdox-<workspace>`, into `~/.claude/settings.json` (nothing else in
+  either file is touched); and, for the project (`--project`, or the only
+  one), `autoMemoryDirectory` in `<checkout>/.claude/settings.local.json`
+  (`--dir`, or the current folder), followed by its first sync.
+- Two steps are left for you, because Claude Code registers a marketplace only
+  once a session has started: open Claude Code once in any folder and close
+  it, then run `claude plugin install <workspace>-setup@systemdox-<workspace>`
+  in your own terminal and accept the command it shows. `setup` never adds the
+  marketplace through `claude` and never enables the plugin for you.
+- `--yes` answers for you only without a terminal, and only for what you have
+  accepted before; anything new or changed is listed and stops the run.
+- Exit codes: `0` done, `1` usage / no key / API error, `2` your edited team
+  `CLAUDE.md` would be replaced (named), `3` Claude Code missing or too old,
+  `4` not confirmed (you answered N, or `--yes` met something new).
+
+Each project's team memory is synced file by file with one command, which you
+run in your own terminal:
+
+```bash
+npx -y @systemdox/mcp-server sync-memory [--project <name>] [--dir <folder>] [--import <folder>] [--dry-run]
+```
+
+- The folder is `--dir`, or `~/.claude/systemdox/<workspace>/memory/<project>/`.
+  Only `feedback`, `project` and `reference` memories and `MEMORY.md` are
+  shared; a `user` memory, a file with `share: false` and a
+  `<name>.local-<date>.md` conflict copy never leave your computer, and the
+  sync never touches them.
+- A file changed only here goes up, one changed only by the team comes down,
+  and one changed on both sides keeps the team's text under its name and yours
+  beside it as `<name>.local-<date>.md`. `MEMORY.md` is merged line by line.
+- Each phone number or email address is asked about once for the whole
+  workspace: `m` a member's contact, `p` someone else (with a role label, never
+  a name), `o` ours, not a person, `x` leave these files out (`share: false`),
+  `s` skip for now. After one `y/N` over the whole diff, each person becomes
+  their identifier (`` `con_…` (reseller, sales) ``) and a home folder `~`.
+- `--import <folder>` merges a second copy of the same memory in (your first
+  sync), keeping every difference as a pair; that folder is not changed.
+  `--dry-run` shows what would be pulled, pushed, deleted, conflicted and
+  skipped, and how many values are still to answer; it asks, writes and sends
+  nothing.
+- Exit codes: `0` synced (conflict copies and skipped files are listed, not
+  errors), `1` usage / no key / API error, `2` the team memory moved on twice
+  while syncing (your folder holds the merge; run it again).
+
+Claude Code runs two commands itself; you never type them:
+
+```bash
+npx -y @systemdox/mcp-server marketplace-auth
+npx -y @systemdox/mcp-server plugin-path <workspace> --version <n> --sha256 <hash>
+```
+
+- `marketplace-auth` gives Claude Code the header for your team's marketplace.
+  It gives your key only for a SystemDox team marketplace on the API's own host
+  (`SYSTEMDOX_API_URL`, https), and only for that workspace; anything else gets
+  nothing and exit `1`. No network call, nothing written.
+- `plugin-path` prints the folder of your team's plugin version. A version
+  already on your computer is printed with no network call. Otherwise it
+  downloads the zip, refuses it unless its SHA-256 is the one Claude Code
+  named, refuses an entry that is absolute, contains `..`, is a link or takes
+  the plugin past 20 MB, and only then unpacks it into
+  `~/.claude/systemdox/<workspace>/plugin/<n>/`. Exit codes: `0` the folder is
+  printed, `1` usage / no key / API error, `2` the SHA-256 differs or an entry
+  was refused.
+
+Both read your key from `SYSTEMDOX_API_KEY`, then from
+`~/.claude/systemdox/credentials.json` for the workspace (readable by you
+alone). A key is never written into a settings file, a plugin entry or a
+command line.
+
 ### `get_context`
 
 The aggregator. It ranks checks, specs and docs against the task, then