@synadia-ai/agent-fabric-claude-code 0.0.0-stage → 0.2.0

package/skills/configure/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: configure
+description: Configure NATS channel - select context, set owner/session, sender identity, inbound trust, and permissions. Use when user asks to set up NATS, connect to NATS, change context, identity, trust, or permissions.
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Bash(ls *)
+  - Bash(mkdir *)
+  - Bash(nats context ls *)
+  - Bash(cat *)
+  - Bash(*list-contexts*)
+effort: low
+---
+
+# /nats-channel:configure - NATS Channel Configuration
+
+Configures the NATS channel plugin: connection context, session name, sender
+identity, inbound sender trust, and permission handling. State lives in
+`~/.claude/channels/nats/config.json`.
+
+Arguments passed: `$ARGUMENTS`
+
+---
+
+## Dispatch on arguments
+
+### No args - status, list, and offer to change
+
+Read state and give the user a complete picture, then ask:
+
+1. **Current config** - read `~/.claude/channels/nats/config.json`. Show:
+   - Selected context name (or "none - using demo.nats.io")
+   - Owner override (if set)
+   - Session name override (if set)
+   - Sender identity mode (`off` or `signed`; default `off`)
+   - Minimum sender trust (`any` or `signed`; default `any`)
+   - Connection URL and description from the context file
+   - Permission mode (`terminal` or `query`) and whether permission prompts
+     will be relayed as NATS query chunks or handled in the local terminal
+
+2. **Available contexts** - run the `list-contexts.sh` script bundled
+   alongside this skill file to list all NATS CLI contexts with their
+   URL and description.
+
+3. **Ask the user** - show the numbered list of available contexts and
+   ask if they'd like to switch. Example:
+   - *"Currently using `<name>`. Available contexts:"*
+   - *(numbered list)*
+   - *"Would you like to switch? Enter a context name or number, or
+     'no' to keep the current selection."*
+   If no config is set, skip straight to asking them to pick one.
+
+### `list` - list available NATS contexts
+
+Two separate steps - do NOT combine into one Bash call:
+
+1. Bash: run the `list-contexts.sh` script bundled alongside this skill
+   file. It produces no stdout - it writes to a file.
+2. Read: open `~/.claude/channels/nats/.contexts` and present the
+   markdown table to the user.
+
+### `<context-name>` - select a context
+
+1. Treat `$ARGUMENTS` as the context name (trim whitespace).
+2. Verify `~/.config/nats/context/<name>.json` exists. If not, show
+   available contexts and error.
+3. Read the context file. Show the URL and description so the user can
+   confirm it's correct.
+4. `mkdir -p ~/.claude/channels/nats`
+5. Read existing `config.json` if present; update/add the `context` field,
+   preserve other fields (like `sessionName`, `permissions`). Write back.
+6. Confirm, then show the status view so the user sees where they stand.
+
+### `session <name>` - set session name override
+
+1. The session name is the 5th token in the v0.3 verb-first subject
+   `agents.prompt.cc.<owner>.<name>`. It defaults to the working directory
+   basename. This command overrides it.
+2. Read existing `config.json` (or start fresh). Set `sessionName` field.
+   Write back.
+3. Confirm the override.
+
+### `session clear` - remove session name override
+
+Remove the `sessionName` field from `config.json` so the default
+(CWD basename) is used.
+
+### `owner <name>` - set owner override
+
+1. The owner is the 4th token in the v0.3 verb-first subject
+   `agents.prompt.cc.<owner>.<name>`. It defaults to the sanitized
+   `$USER`. This command overrides it — useful for service accounts or
+   deployment-scoped owners.
+2. Read existing `config.json` (or start fresh). Set the `owner` field.
+   Write back.
+3. Confirm the override. Note: the `SYNADIA_CLAUDE_CODE_OWNER` and
+   `SYNADIA_OWNER` env vars take precedence over this config field.
+
+### `owner clear` - remove owner override
+
+Remove the `owner` field from `config.json` so the default (sanitized
+`$USER`) is used.
+
+### `identity off` - disable host identity
+
+Set `senderIdentity` to `"off"`. The channel performs no host identity lookup
+and registers no identity metadata. This is the default and works with
+token/password authentication and servers where user-info lookup is not
+permitted. It does not change inbound sender policy.
+
+### `identity signed` - use the connection identity
+
+Set `senderIdentity` to `"signed"`. The selected NATS context must contain a
+user seed (`creds`, `nkey`, or `user_jwt` plus `user_seed`). The same immutable
+credential snapshot supplies both connection authentication and signing; never
+ask for or add a second identity credential. Signed startup fails rather than
+downgrading when the connection cannot be bound to that signer.
+
+`NATS_SENDER_IDENTITY` overrides this config field. A plugin reload or Claude
+Code restart is required after changing it.
+
+### `trust any` - accept all sender trust classes
+
+Set `minSenderTrust` to `"any"`. Headerless, claimed, and verified prompts are
+admitted. This is the backward-compatible default and is independent of the
+channel's own identity.
+
+### `trust signed` - require verified senders
+
+Set `minSenderTrust` to `"signed"`. Headerless, claimed, malformed, stale, and
+replayed requests are rejected before an acknowledgement and before Claude sees
+the prompt. `NATS_MIN_SENDER_TRUST` overrides this config field.
+
+### `permissions terminal` - use terminal for permission prompts
+
+Set `permissions.mode` to `terminal`. Permission prompts will appear in the
+Claude Code terminal session. This is the simplest option when the operator
+has direct terminal access, and the default when no permissions block is set.
+
+1. Read existing `config.json` (or start fresh).
+2. Set `permissions` to `{ "mode": "terminal" }`.
+3. Write back and confirm.
+
+### `permissions query` - relay permissions as query chunks
+
+Set `permissions.mode` to `query`. When Claude needs permission to use a
+tool during an active NATS prompt, the plugin emits a protocol `query`
+chunk (§7 of the Synadia Agent Protocol for NATS) on the active stream's reply
+subject. The caller replies with `yes`/`no` on the query's dynamic reply
+inbox, and the plugin forwards the decision back to the Claude Code
+harness. The legacy value `"nats"` is accepted as an alias for
+backward compatibility.
+
+If Claude asks for permission while no NATS request is active, the request
+is denied (there is no open stream to carry a query chunk on). Operators
+who need terminal-style prompting in that case should use `permissions
+terminal` instead.
+
+1. Read existing `config.json` (or start fresh).
+2. Set `permissions` to `{ "mode": "query" }`.
+3. Write back and confirm.
+
+### `permissions clear` - reset to default
+
+Remove the `permissions` field from `config.json`, restoring the default
+behavior (terminal-mode prompts).
+
+### `clear` - remove config
+
+Delete `~/.claude/channels/nats/config.json`.
+
+---
+
+## Implementation notes
+
+- The channels dir might not exist if the server hasn't run yet. Missing
+  file = not configured, not an error.
+- The server reads `config.json` once at boot. Config changes need a
+  session restart or `/reload-plugins`. Say so after saving.
+- NATS CLI contexts live in `~/.config/nats/context/<name>.json`. Each
+  file contains `url`, `description`, `creds`, `nkey`, `user`, `password`,
+  `token`, `cert`, `key`, `ca`, and other fields.
+- Do not modify NATS CLI context files - only read them.
+- `senderIdentity` and `minSenderTrust` are independent. Do not enable strict
+  inbound policy merely because signed host identity was enabled.
+- Legacy configs with `"mode": "nats"` are still accepted and treated as
+  the new `"query"` mode; they do not need to be rewritten.
+- Legacy configs with `permissions.subject` are silently ignored - query
+  chunks use a dynamic reply inbox per request, not a fixed subject.

package/skills/configure/list-contexts.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# List NATS CLI contexts as a markdown table.
+# Writes to ~/.claude/channels/nats/.contexts for the skill to Read.
+
+CONTEXT_DIR="${HOME}/.config/nats/context"
+STATE_DIR="${HOME}/.claude/channels/nats"
+OUT="${STATE_DIR}/.contexts"
+
+mkdir -p "$STATE_DIR"
+
+if [ ! -d "$CONTEXT_DIR" ]; then
+  echo "No NATS contexts found (${CONTEXT_DIR} does not exist)" > "$OUT"
+  exit 0
+fi
+
+{
+  echo "| Name | URL | Description |"
+  echo "|------|-----|-------------|"
+  jq -r 'input_filename as $f |
+    [($f | split("/") | last | rtrimstr(".json")), (.url // "-"), (.description // "-")] |
+    "| \(.[0]) | \(.[1]) | \(.[2]) |"' "$CONTEXT_DIR"/*.json 2>/dev/null
+} > "$OUT"

package/skills/scratchpad/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may act only on Your own behalf and
+      on Your sole responsibility, not on behalf of any other Contributor,
+      and only if You agree to indemnify, defend, and hold each Contributor
+      harmless for any liability incurred by, or claims asserted against,
+      such Contributor by reason of your accepting any such warranty or
+      additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!) The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Synadia Communications
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions
+   and limitations under the License.

package/skills/scratchpad/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: scratchpad
+description: Read ScratchPad references (sp-r1:… or sp-ref:…) handed to you, and publish, share, hydrate and recover bounded ScratchPad artifacts of your own, through this skill's scripts/sp.
+allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/sp *)
+---
+
+# ScratchPad
+
+Adapted from the canonical ScratchPad skill for an agent on the fabric.
+The packaged `bin/BUILD.json` records the release, opaque source identifier,
+toolchain, targets, and executable hashes. `LICENSE` and
+`THIRD_PARTY_NOTICES` contain the distribution terms.
+Run the sp command line only as this skill's `scripts/sp`, by its absolute
+path: the directory of this file, then `scripts/sp`. In the examples below,
+`scripts/sp` stands for that path.
+
+Run each `scripts/sp` command on its own: its absolute path written out in
+full, no shell variable for it, no `cd`, `;` or `&&` around it, and its
+output not piped into another command. Content may come in on standard
+input (`printf '%s\n' "$TEXT" | scripts/sp publish-file --source - …`).
+Decode `data_base64` in a command of its own:
+`echo "$DATA_BASE64" | base64 -d`. A harness that asks before running a
+shell command can then allow `scripts/sp` by its path, and does not ask.
+
+`scripts/sp` adds what the examples in ScratchPad's own skill pass by hand:
+the NATS server, this agent's credentials, its workspace, its volume on
+`init`, the trace of the prompt you are serving, your address as the
+creator of what you publish, and the agent that prompted you as the grantee
+of a grant. Never pass `--url`, `--creds`, `--dir`, `--volume`,
+`--thread-id`, `--root-id`, `--creator`, `--grantee-account` or
+`--grantee-user` yourself; `scripts/sp` refuses them.
+
+## Keep identity and recovery state
+
+The connection uses this agent's own identity.
+The service authenticates the connection; a reference, creator label, or trace field supplies no identity.
+The workspace is private to this agent and persists across restarts.
+
+Each successful command prints JSON.
+Read the returned receipt before reporting that publication succeeded.
+An upload alone does not publish a checkpoint.
+Retention preserves the root until explicit release.
+Its deadline permits later client cleanup.
+A grant separately permits one authenticated principal to read that root and path.
+Do not print credential contents.
+
+## Read an artifact handed to you
+
+A reference is one token that starts with `sp-r1:`. Copy the complete token exactly.
+Services that do not enable short references return a longer `sp-ref:` token; copy that token unchanged too.
+Keep the returned token in prompts and replies. Do not expand, shorten, repair, or reconstruct it.
+A short reference can be read after an agent restart; it does not depend on a session alias table.
+
+```sh
+scripts/sp read --ref "$REFERENCE"
+scripts/sp hydrate --ref "$REFERENCE" --destination "$DESTINATION"
+```
+
+Read returns verified bytes as `data_base64` and their count as `bytes`; decode `data_base64` to get the content.
+Read accepts files up to 16 MiB; use hydration for larger files and directory trees.
+`limits.read_bytes` from `info` bounds one service range request; the CLI combines ranges for this buffered read.
+Hydrate requires a destination that does not exist.
+It verifies content identities before completing files, and reports the files, directories, symbolic links and bytes it installed.
+Failure can leave a partial destination; preserve that path for inspection.
+An expired reference or refused grant does not authorize another identity or path.
+
+## Initialize and inspect
+
+```sh
+scripts/sp info
+scripts/sp init --operation-id "$CREATE_ID"
+scripts/sp describe
+```
+
+`info` returns this agent's authenticated principal, owned scope allowances, and request limits.
+It needs no initialized workspace and changes no recovery state.
+The scope byte and object figures are configured allowances; `describe` shows current usage.
+An empty scope list needs an operator admission check before this agent can publish.
+Volumes readable through another owner's grant are not listed; their granted references can still be read.
+If `info` reports an unknown command, an older binary was selected; continue with the existing commands and ask the operator for the allowances.
+
+`init` creates this agent's volume once; publishing needs it.
+Rerun the saved creation action after an unknown outcome.
+An established writer whose journal disappeared requires an explicit reset.
+Initialization cannot silently reset that writer.
+
+## Publish a file and share it with the agent that prompted you
+
+`SOURCE` names the local file, or `-` for standard input; `ARTIFACT_PATH` is its canonical absolute artifact path, such as `/replies/1.txt`.
+Use a new `OPERATION_ID` for each intended publication.
+A rerun with the same operation identifier returns that publication's saved result; it never reads the source again, so changed content needs a new identifier.
+
+```sh
+scripts/sp publish-file --source "$SOURCE" --path "$ARTIFACT_PATH" --operation-id "$OPERATION_ID" --ttl-seconds 600
+```
+
+Copy the returned `reference` without editing its contents.
+This command publishes a complete root containing that one file.
+It also retains the root in the same atomic publication.
+While you serve a prompt, it also grants the agent that prompted you read on that file: the result's `granted_to_caller` says so, and `caller_grant_error` says why not.
+Then put the unchanged reference in your reply.
+
+To grant that agent read again, for example after the grant expired:
+
+```sh
+scripts/sp grant --ref "$REFERENCE" --operation-id "$GRANT_ID" --ttl-seconds 600
+```
+
+A grant goes to the agent whose prompt you are serving, and to no one else.
+The returned expiry can be earlier than requested because the grant cannot outlive its retained root.
+
+## Hand a reference to another agent
+
+Put the unchanged reference in the prompt of `prompt_agent`, and nothing
+more: do not grant for it yourself. The agent tools grant the receiver read
+when it reads references (`discover_agents` shows
+`reads_scratchpad_references: true`), and take the reference out of the
+prompt otherwise, saying so in the call's result. A reference another agent
+handed you goes on the same way; its creator decides whether the receiver
+may read it.
+
+## Publish an edited directory
+
+An external editor or executor prepares `SOURCE_DIRECTORY`.
+ScratchPad does not run that editor or executor.
+
+```sh
+scripts/sp sync --source "$SOURCE_DIRECTORY" --operation-id "$OPERATION_ID"
+```
+
+Sync publishes the whole directory as the next root.
+Paths absent from that directory are absent from the new root.
+Preparation copies canonical content into a private disk spool in the workspace before upload.
+It preserves executable file modes and literal symbolic links without following links.
+There are no implicit Git exclusions; choose the source tree explicitly.
+Another writer's publication can produce an explicit conflict; the command does not merge automatically.
+
+## Resolve a failed command
+
+| Exit | Action                                                                             |
+| ---- | ---------------------------------------------------------------------------------- |
+| 0    | Inspect the successful JSON result.                                                |
+| 1    | Inspect the definite failure code and workspace state.                             |
+| 2    | Correct the local arguments; no product request was sent.                          |
+| 3    | The outcome is unknown. Recover the saved intent before starting another mutation. |
+
+```sh
+scripts/sp recover
+```
+
+Recovery first reconciles an exact accepted receipt.
+If publication remains necessary, recovery uploads the saved spool and submits the same command.
+It never rereads a changed source file or standard input.
+An `epoch_changed` response requires preparation against the current collection epoch; rerun recovery after maintenance ends.
+Do not change its operation identifier, base, root, or requested retention while the outcome remains unresolved.
+A definite conflict can leave the publication pending.
+Inspect an explicit reset plan before abandoning that intent.
+
+```sh
+scripts/sp reset
+scripts/sp reset --apply
+```
+
+Reset fences the previous writer generation.
+It does not release retention from an earlier unknown publication.
+An unresolved grant can block further control operations until acceptance, a positive observation, or expiry settles it.
+
+A publication refused before its checkpoint was prepared leaves its spool, and so does a publication abandoned by reset.
+A later publication requires recovery or explicit removal of that saved upload.
+Inspect the spool before attempting removal:
+
+```sh
+scripts/sp spool-inspect
+scripts/sp spool-remove
+scripts/sp spool-remove --apply
+```
+
+### Remove an unprepared upload
+
+Removal is a dry run without `--apply` and refuses a pending checkpoint.
+A refused upload can be removed without reset when its writer remains ready at the saved command position.
+Inspect the removal report before applying it.
+Removal abandons the saved upload, including bytes read from standard input.
+Remote reservations remain charged until maintenance collects them.
+An older workspace can already have a pending checkpoint after an upload refusal.
+Do not automatically reset it because a response says `capacity`; recover or inspect an explicit reset first.
+A new publication reclaims a completed previous spool only after its exact receipt is saved.
+
+## Reclaim expired content
+
+```sh
+scripts/sp maintain
+scripts/sp maintain --apply
+```
+
+The first command reports the proposed maintenance.
+The second releases unprotected expired pins, closes the volume, traces retained dependencies, collects unreachable objects, and reopens it.
+Maintenance does not scrub retained file payloads.
+If interrupted, recover the saved request or repeat maintenance against the durable closed state.
+Capacity refusal requires maintenance or an explicit operator decision; it never permits eviction of retained content.
+
+## Capacity
+
+Deployment scopes select explicit encoded-byte and object quotas.
+Read this agent's configured allowances with `scripts/sp info`; example sizes are not deployment defaults.
+Objects include chunks, file metadata, and directories.
+Retained results and unfinished uploads consume the same allowance.
+Replacing unique content needs room for both versions until old retention is released and collection completes.
+Local spools also need enough private disk space for the prepared artifact.