accrete-kit 0.0.0-stage → 0.1.0

package/dist/scaffold/assets/skills/accrete-data/references/remote-and-retention.md

@@ -0,0 +1,98 @@
+# Remote Data and retention
+
+## Separate meaning from placement
+
+Shared project configuration names logical roots, locations, and useful
+environment labels. `.accrete/local.toml` supplies the current host's physical
+paths and native transfer bindings. Relative configured paths resolve against
+the ACCRETE project root. A remote Model checkout, large payload, and Scratch
+directory can all live outside that root.
+
+Use the CLI's explicit `--project` selector from external working directories.
+Do not infer the project from whichever Model repository happens to be the
+current directory. Returned mutation paths identify the affected descriptor
+and usable destination.
+
+Credentials remain in native SSH, rclone, storage, or environment configuration.
+Describe an endpoint by its configured alias and path. Avoid retaining tokens,
+full credential-bearing URLs, or indiscriminate environment dumps in Results,
+Memory, input drafts intended for Git, or shared TOML.
+
+## Remote production and local analysis
+
+Use ordinary SSH, schedulers, domain launchers, and scientific programs for
+remote execution. Register completed products where they exist and describe
+the actual activity with Results. Exchange small descriptors and useful Memory
+through the project's selected Git, or with `accrete export` and `accrete import`,
+whose bundles carry descriptors and leave payloads where they are. Transfer only
+the products required for the next analysis.
+
+A locally received descriptor can correctly name a remote output that is not
+downloaded. It can also retain an old availability observation when the remote
+host is currently unavailable. For current process and storage state, consult
+the owning host's tools. A copied Result saying `running` is historical prose,
+not a current process observation.
+
+Independent clones have separate local state. A host-local Kernel lock and
+SQLite index do not coordinate simultaneous writers across compute nodes on
+a network filesystem. Use one selected metadata-writing host or separate
+metadata views and exchange documents afterward. Read-only payload sharing
+can continue through the scientific storage system.
+
+## Materialization and large products
+
+Prefer registering in place when bytes are already where they are needed.
+Materialize when another managed usable copy has a purpose. The Kernel copies
+locally or downloads through configured rclone, stages incomplete content separately,
+then publishes the completed replica and its location association. The metadata lock
+is held only for publication, not for the transfer duration.
+
+Content identification should match the actual knowledge and cost:
+
+| Existing information | Appropriate description |
+| --- | --- |
+| Producer SHA-256 for a selected file | Supply it as `content.sha256`. |
+| Producer collection manifest | Retain the manifest and what it describes. |
+| Immutable provider version | Describe it in `content.edition` and keep the selector on the location as an opaque token. `data materialize` refuses such a source, so use a version-specific exported locator or retrieve it with the provider's tool. |
+| Closed directory with known provenance | Retain the producer's content description; omit an uncomputed digest. |
+| Mutable external path | Identify it as live and describe the observation time. |
+
+Hashing and archive creation are explicit choices. Avoid scanning terabytes
+merely to assign an identity. Do not label backend completion as stronger
+content checking than the transfer actually performed.
+
+If a transfer stops, run `accrete recover` on that host. A lost acknowledgment can
+leave a completed replica whose descriptor update remains pending, and recovery
+finishes that from the receipt. An incomplete transfer is reported with its staging
+path and left for explicit retry or cleanup. Inspect that specific outcome before
+beginning another transfer; never rerun the producing simulation as metadata recovery.
+
+Uploading to a remote is a native rclone operation followed by `data location add`.
+Object storage can publish individual objects without atomically publishing an entire
+directory collection, so upload to a fresh prefix and add the location only when the
+upload finishes. Do not make an already-used complete prefix temporarily stand for a
+different partially uploaded edition.
+
+## Evict a replica deliberately
+
+Distinguish these changes:
+
+- Evicting one managed replica removes that copy and updates its availability.
+- Retiring current use with `accrete data retire` keeps the identity and earlier
+  Result associations, and removes no bytes.
+- Deleting a borrowed source is an explicit action by its owner.
+
+Registration does not grant the Kernel authority to delete a borrowed
+scientific directory. A managed materialization can be evicted with `accrete data
+evict` for that exact location. Other recorded locations help a
+decision, but their availability may be stale; the project index cannot know
+every external use or unpublished computation.
+
+Keep symlink and hard-link behavior visible. A link to mutable producer bytes
+does not make an independent closed copy. Materialization copies and never hard-links
+a source, and it refuses symlinks, so package links deliberately when they matter.
+
+Describe useful retention choices in Memory: why an edition matters, which
+products were selected, what remains remote, and what the host may purge.
+The word Scratch alone specifies no expiry duration. Site storage policies
+govern the actual bytes; ACCRETE preserves the project's descriptions of them.

package/dist/scaffold/assets/skills/accrete-memory/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: accrete-memory
+description: Preserve and recover ACCRETE project understanding across sessions and agents. Use when retaining reasoning, lessons, interpretations, rejected explanations, useful decisions, corrections, or next directions linked to Models, Tools, Data, Results, and earlier Memory. Use native search to read relevant entries and the Kernel to publish complete authored Markdown.
+---
+
+# ACCRETE Memory
+
+Preserve understanding that will help later work: what was learned, why a
+choice was made, which explanation failed, what remains uncertain, and what
+can be tried next. Write plain prose in the project's language. Memory belongs
+to the project and remains useful beyond one host conversation.
+
+## Recover relevant understanding
+
+Search the configured Memory root with `rg` and read the entries relevant to
+the current question. Follow their Result, Model revision, Data, or Tool links
+as needed. Loading the entire history at the beginning of every action is
+unnecessary. Trust prior work within its recorded scope; repeat it when the
+present task or a concrete changed condition calls for it.
+
+Keep historical understanding distinct from present machine state. A note
+about a running job or checkout describes its authored context. Use Git,
+the scheduler, process tools, and current configuration for today's state.
+Project summaries help navigation; the user's current instruction governs
+the current task.
+
+## Publish a useful complete entry
+
+Draft the complete Markdown text in Scratch or another ordinary working file.
+Use `accrete memory append --from DRAFT_PATH` and supply known relations, such as
+`--result RESULT_ID`. The Kernel allocates the stable entry ID, unless you supply
+`--id` for retries, and publishes the complete entry at the next local date-based
+path. Keep the returned ID and path in the handover where useful.
+
+The default path is `memory/YYYY/MM/DD/NNN.md`; configuration can place Memory
+elsewhere. The project timezone determines the publication day. The stable
+frontmatter ID identifies the entry even if an import renumbers its filename.
+Do not preallocate permanent empty entries or maintain numbering with a
+separate script.
+
+Write a later entry with `--supersedes EARLIER_ID` when an interpretation changes.
+Explain what changed and which earlier understanding it supersedes, while retaining
+the earlier prose. Use Results for activity descriptions and observations, and
+Data for retained payloads. A Memory entry can synthesize several activities
+without repeating all their detailed metadata.
+
+## Keep the process open
+
+Write when the understanding is worth carrying forward. A worker may publish
+delegated Memory through the same Kernel operation; a Coordinator may instead
+combine several findings. There is no required diary frequency, fixed section
+form, grading step, or universal exclusive writer.
+
+- [Writing and continuity](references/writing-and-continuity.md): useful
+  content, corrections, topic summaries, and links between objects.
+- [Command manual](references/commands.md): drafts, append operations,
+  native search, concurrent numbering, and operation outcomes.
+- [Handovers and remote work](references/handovers-and-remote-work.md):
+  self-contained returns, imported entries, and durable project experience.
+
+`accrete memory append --help` prints the flags.

package/dist/scaffold/assets/skills/accrete-memory/references/commands.md

@@ -0,0 +1,124 @@
+# Memory command manual
+
+## Contents
+
+- Interface and native reading
+- Publish authored understanding
+- Link objects and earlier understanding
+- Identity, dates, and concurrent work
+- Publication outcomes
+
+## Interface and native reading
+
+This manual covers `memory append`. The full contract is at project-root path
+`.accrete/docs/cli-contract.md`, and `accrete memory append --help` prints the flags.
+
+Search and read Memory with ordinary tools. For the default configured root:
+
+```sh
+rg -n 'routing|cold start|reuse' memory
+rg -n 'RESULT_ID_OR_MEMORY_ID' memory
+```
+
+Replace the search terms with those relevant to the task. Follow actual paths
+returned by search or publication; configure other Memory roots normally.
+Reading Markdown does not require an ACCRETE read command. SQL can query
+the configured host-local projection, whose freshness is independent of the
+durable files.
+
+Global `--project DIRECTORY` selects the owning project. `ACCRETE_PROJECT` is the
+fallback selection before ancestor-directory discovery. Use the explicit
+selector when a worker operates in an external Model checkout or run directory.
+Global `--json` returns a machine-readable receipt on stdout; diagnostics go
+to stderr.
+
+## Publish authored understanding
+
+Write a complete Markdown body in a normal working file. Choose its structure
+according to the substance; no fixed headings are required. Submit it with:
+
+```sh
+accrete --json memory append --from scratch/understanding.md
+```
+
+The Kernel allocates the stable ID, date-based path, authored metadata, and
+requested associations and publishes the complete entry. It returns the ID,
+concrete path, and revision. The source draft remains ordinary working material.
+Do not reserve an empty permanent entry by manually creating its target path.
+`--title TITLE` names the entry, and `--authored-at` supplies an explicit RFC 3339
+instant; the date directory still uses the current project-local day.
+
+Input can be prepared anywhere that the selected host can read. Keep shared
+project content free of native credentials and arbitrary environment dumps.
+A useful interpretation can refer to a Tool or Result instead of embedding
+its entire raw log.
+
+## Link objects and earlier understanding
+
+Relation flags repeat:
+
+```sh
+accrete --json memory append --from scratch/understanding.md \
+  --result "$RESULT_ID" --data "$DATA_ID" --model "$MODEL_ID"
+```
+
+Use `--tool TOOL_ID` for relevant capabilities. Repeating a flag links several
+objects of that kind. Relations may remain unresolved locally when the target
+belongs to another working copy. Supply actual stable IDs and keep readable context
+in the body.
+
+For a correction, draft a later entry explaining the change and name the entry it
+replaces:
+
+```sh
+accrete --json memory append --from scratch/correction.md \
+  --supersedes "$EARLIER_MEMORY_ID" --result "$NEW_RESULT_ID"
+```
+
+Omit a relation whose target does not exist. If there is no new Result, the
+correction can still link earlier Memory and explain its basis in prose.
+The relationship alone does not express the correction's meaning; write what
+changed and why.
+
+For a link `--supersedes` does not describe, such as a related earlier entry or a
+link carrying a revision or role, use `--links-from FILE` with a JSON array:
+
+```json
+[{ "kind": "memory", "id": "EARLIER_MEMORY_ID", "relation": "continues" }]
+```
+
+## Identity, dates, and concurrent work
+
+The default published layout is `memory/YYYY/MM/DD/NNN.md`. The configured
+project timezone determines the publication date. The entry's frontmatter ID
+is stable across renaming; the authored instant remains distinct from the
+date used for display. Simulation time belongs in the scientific description.
+
+Local Kernel publication serializes sequence allocation so concurrent local
+writers receive distinct paths. Each worker can submit a complete delegated
+entry using the same operation. The Coordinator may synthesize entries when
+that better preserves the understanding.
+
+Independent hosts can choose the same date and display number. `accrete import`
+preserves both IDs and authored instants and may renumber a filename. If Git produces
+a path collision, preserve both complete entries and resolve the paths. Use IDs
+for durable associations, and update human path links where necessary.
+
+## Publication outcomes
+
+When retryability matters, supply `--id ID` from the first attempt: 1-180 ASCII
+letters, digits, dots, underscores or hyphens, and not `.` or `..`. Retain it before
+submission. Repeating with the same ID and unchanged content reconciles the same
+publication; it does not allocate another numbered entry. Reusing an ID with
+different content produces a conflict. Use a new entry for a new interpretation.
+
+`committed: true` means the Markdown publication completed. When
+`index_pending: true` accompanies it, run `accrete index refresh`; do not append
+the entry a second time. If a destination is published but durability is
+reported uncertain (exit 8), keep its path and run `accrete recover`.
+
+Input rejection before publication leaves the draft available for correction.
+Lost acknowledgments and partial publication require inspecting the specific
+receipt or destination before retrying. Recovery concerns publication and
+projection; it never reruns an experiment or rewrites the interpretation
+on the agent's behalf.

package/dist/scaffold/assets/skills/accrete-memory/references/handovers-and-remote-work.md

@@ -0,0 +1,78 @@
+# Handovers, remote work, and continuing experience
+
+## Give the next agent usable context
+
+A handover tells the next participant what happened, where the material is,
+what it suggests, and what remains open. Include the object IDs and concrete
+paths needed for the next action. Name relevant revisions, the execution host,
+and local bindings when they affect the work. Say which writes or transfers
+remain incomplete instead of asking a new agent to reconstruct that state
+from a large transcript.
+
+Memory preserves the interpretation that will remain useful beyond that
+handover. A returned task description need not automatically become a Memory
+entry. A coordinator can synthesize several workers' findings into one entry,
+or a worker can publish delegated understanding directly through the Kernel.
+
+Neither arrangement needs a fixed permission token or universal exclusive
+writer. Give workers a clear purpose, relevant objects, chosen working paths,
+and the scope of their responsibility. Coordinate overlapping native edits
+and scarce compute resources according to the actual task.
+
+## Maintain project context outside the project root
+
+A worker may operate in a separate Model worktree or on a remote host. Supply
+the ACCRETE project root and relevant guidance explicitly. The Model's Git
+root may be a different repository from the project containing Memory.
+Use `--project` for Kernel operations outside that root.
+
+Do not assume a new agent session inherited every conversation or discovered
+project instructions from a different directory. A brief should identify the
+current objective and useful context in normal prose. The agent remains free
+to investigate beyond the supplied paths when the task calls for it.
+
+## Exchange entries across hosts
+
+Each host has its own local state and metadata view. Exchange durable Markdown
+through the project's Git practice, or as a metadata bundle when no shared remote
+exists:
+
+```sh
+accrete export --to handoff.json --id MEMORY_ID --id RESULT_ID
+accrete import --from handoff.json
+```
+
+Omit `--id` to export every managed document. The bundle carries documents, not
+scientific payloads, Git objects, Tool source, or machine bindings, so name what stays
+behind in the handover. Import reports each object's outcome and is not atomic;
+repeating the bundle completes what is missing. Host-local locks allocate filenames for local writes only. Two disconnected
+hosts can both publish `memory/2026/11/03/001.md` with different stable IDs.
+
+Preserve both entries when they meet. `accrete import` allocates a new display
+number for one while retaining its ID and authored instant, and records the original
+path as `origin_path`. If ordinary Git
+reports a path collision, resolve the filenames with that same meaning. Do
+not combine unrelated bodies merely because they selected the same number.
+
+Machine-readable relations use stable IDs. The Kernel does not rewrite links in
+authored prose. Update a human path link when necessary while preserving the
+intended target identity.
+
+A copied Memory entry can describe remote products that remain remote. Use
+its Data and Result links to request the needed material. It does not imply
+that the remote computation is still running or that an old locator remains
+available. Present state comes from the owning host's native tools.
+
+## Let experience change the working environment
+
+An explanation that repeatedly guides useful work can be developed into a
+Tool: a diagnostic method, a domain reading guide, a launcher, or a reusable
+analysis. Author its source with ordinary tools and admit it through the Tool
+Skill when useful. Memory can explain why it exists and where its limits were
+learned.
+
+Similarly, findings can motivate a Model iteration or a different Data
+selection. Carry those relations forward without requiring every Memory entry
+to create a task, every lesson to become a Skill, or every exploration to follow
+a fixed research cycle. The owner and agents choose how experience informs
+subsequent work.

package/dist/scaffold/assets/skills/accrete-memory/references/writing-and-continuity.md

@@ -0,0 +1,101 @@
+# Writing understanding that remains useful
+
+## Contents
+
+- What to carry forward
+- Relating Memory to other objects
+- Corrections and uncertainty
+- Reading and topic summaries
+- Optional writing patterns
+
+## What to carry forward
+
+Retain understanding whose value outlives the current exchange. Useful entries
+explain a mechanism, an implementation decision, a diagnostic interpretation,
+an unsuccessful direction, a practical constraint, or a promising continuation.
+An entry can be brief when a short explanation preserves the essential point.
+
+Write enough context for another agent to understand the claim without having
+seen the conversation. Name relevant revisions, Result IDs, Data editions, or
+Tool implementations when they materially delimit the lesson. Distinguish what
+was observed from what is inferred, and describe the conditions under which
+the understanding is useful.
+
+Do not convert every transient terminal line into project Memory. Raw outputs,
+long logs, arrays, and code already have suitable locations. Link them through
+Results and Data when retained. Host transcripts and private agent context can
+continue to exist separately; Memory is the authored project synthesis.
+
+## Relating Memory to other objects
+
+| Subject of an entry | Useful relation |
+| --- | --- |
+| An observation from an experiment | Relevant Result and Model revision. |
+| Why a numerical fix changed behavior | Result comparison, changed implementation, and any relevant Tool. |
+| A useful analysis method | The retained Tool and Results demonstrating its use. |
+| Data limitations or selection | Data ID/edition and the activity that exposed the limitation. |
+| Revised explanation | Earlier Memory ID and the newer observations motivating the revision. |
+| A next direction | Current question, relevant objects, and the reason for pursuing it. |
+
+Use stable IDs for machine-readable links. Human Markdown links to paths can
+make browsing convenient, but imported date-based filenames can change. Keep
+both identity and an accessible path when useful; do not treat the filename as
+the entry's durable identity.
+
+The body remains prose. Associations help later discovery without requiring
+a formal claim language or replacing the author's explanation. A single entry
+can connect multiple objects and several rounds of experience.
+
+## Corrections and uncertainty
+
+Write a later entry when a new observation changes an earlier interpretation.
+Name the earlier entry with `--supersedes`, state the revised understanding, explain what changed,
+and describe what still holds. Preserve the previous entry so the sequence of
+reasoning remains intelligible.
+
+A correction to execution metadata belongs in a Result amendment. A newly
+observed outcome can be added as an observation. A changed explanation of
+those outcomes belongs in Memory. An additional analysis can produce its own
+Result and then a Memory interpretation. These actions can be taken in the
+order useful to the work.
+
+Preserve uncertainty with ordinary language. A hypothesis can be retained
+without being promoted to an established conclusion. A failed explanation
+can be valuable if the entry says why it was set aside and within what scope.
+Avoid implying that every possibility was ruled out when only one mechanism
+was investigated.
+
+Present machine state can change without invalidating historical reasoning.
+A note saying a particular environment or branch was selected describes its
+authored context. Read current configuration and native state before using
+that information for a new action. Scientific simulation time is a domain
+coordinate; the date used to organize Memory is a publication convention.
+
+## Reading and topic summaries
+
+Search by the current scientific question, a distinctive mechanism, a Result
+ID, or a program component. Read relevant entries and their immediate context.
+Follow links when needed instead of rereading every project entry.
+
+Trust inherited work within the scope it documents. Additional checks belong
+to the current task when a changed implementation, new observation, or owner
+request gives them a purpose. Memory should help work continue rather than
+require routine reenactment of earlier activities.
+
+A topic summary can consolidate a growing line of work and link its detailed
+entries. Treat it as an authored aid that can become outdated. Preserve the
+details needed to understand changes of interpretation. A summary does not
+override the owner's current instruction or determine present runtime state.
+
+## Optional writing patterns
+
+Choose a form suited to the content. A mechanism note can explain the observed
+behavior, the reason it occurs, and its implications. A decision note can state
+the choice, rationale, practical consequences, and circumstances for revisiting
+it. A correction can name the earlier interpretation and explain its revision.
+A short handover synthesis can preserve completed understanding and next
+directions while leaving operational details in the normal task handover.
+
+These are writing options, not required headings. Use the project's ordinary
+academic or engineering prose and retain only the context needed to make the
+entry useful later.

package/dist/scaffold/assets/skills/accrete-models/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: accrete-models
+description: Develop and organize ACCRETE computational Models using native Git and the ACCRETE CLI. Use when registering or binding a model repository, opening or completing a retained development iteration, working across embedded programs, submodules or external checkouts, or associating scientific work with the implementation actually used.
+---
+
+# ACCRETE Models
+
+Treat a Model as the project's durable identity for a computational program. Use Git for its implementation, history, branches, worktrees, and integration. Use the Kernel to register, update or retire the identity, bind a checkout, retain the purpose and outcome of an iteration, or remove an iteration's worktree.
+
+## Orient to the program
+
+Establish the owning ACCRETE project and the actual Model repository. Start from the task's supplied paths and object IDs; use ordinary file search and Git when they are incomplete. A Model can be embedded in the project, scoped to part of a larger repository, a submodule, or an external repository. A checkout is one place to work on that Model.
+
+Keep these addresses distinct:
+
+- The ACCRETE project root selects the objects and configuration to change.
+- The Model ID identifies the program across hosts and checkouts.
+- The repository commit identifies a historical implementation address.
+- The source scope identifies relevant paths when several programs share one repository.
+- The current checkout or worktree is a physical editing or execution location.
+
+Use the project's explicit `--project` selector for Kernel calls made from external checkouts. Resolve shared relative paths from the project root. Follow machine-specific bindings for actual checkout and execution paths.
+
+## Develop through ordinary tools
+
+Read and edit source, build, investigate, and commit using the existing language tools and Git. Choose the amount of retained organization that the work needs. An iteration is useful for a named line of development that later work should understand; it is optional for an ordinary edit.
+
+Open an iteration around its actual Model repository and intended starting revision. An existing worktree can be attached after work has begun. Allocate independent editing locations when workers' changes can overlap. A host-created worktree of the outer project does not automatically isolate a Model in a different repository.
+
+Integrate using the project's ordinary Git strategy. Close an iteration when its outcome is meaningful to retain. Author the outcome in the project's own terms; integrated, retained separately, and abandoned are useful examples. Closing records that outcome and relevant commits. Merging code is separate native Git work, and removing the worktree is the separate `model iteration remove-worktree` step.
+
+## Preserve the implementation used
+
+Associate a Result with the revision actually used by its activity. A current checkout observation is useful only for the time it was observed. For earlier work, use the launcher's captured identity or an explicit historical revision; leave unknown execution identity unknown.
+
+Allow uncommitted work. Describe its dirty state and any captured material without claiming a patch contains every dependency, untracked file, generated input, or runtime condition. `accrete result capture` writes a selected diff and untracked files; retain that as Data when the task needs it. A changed project commit can reflect only new Memory or documentation; source-scope identities can help explain that distinction without deciding scientific equivalence.
+
+Keep earlier Results associated with their original revisions. Consult relevant Memory before repeating a settled investigation. Add a later interpretation when understanding changes; rerun work when the current scientific or engineering question calls for it.
+
+## Read only what the action needs
+
+- [Object meaning and relationships](references/objects.md): choose repository arrangements, understand IDs, roles, iterations, source scope, and retained history.
+- [Kernel operations](references/cli.md): register, bind, update, retire, open, close, and remove a worktree; prepare structured input and handle receipts.
+- [Working across sessions and machines](references/working-practice.md): parallel development, dirty source, execution identity, Git transport, and continuity.
+
+Read the installed `.accrete/docs/cli-contract.md` from the project root for the shared command contract and payload conventions. `accrete model COMMAND --help` prints the flags. On a host without the binary, keep draft input in Scratch and continue useful native work without fabricating an ACCRETE descriptor.

package/dist/scaffold/assets/skills/accrete-models/references/cli.md

@@ -0,0 +1,117 @@
+# Model Kernel operations
+
+This manual covers the Model commands. `.accrete/docs/cli-contract.md` has the shared conventions and `accrete model COMMAND --help` prints the flags. Keep structured inputs in ordinary files under the configured Scratch root.
+
+Contents: [operations](#operations-and-supplied-information), [inputs](#prepare-a-change), [receipts](#use-the-mutation-response), [native work](#native-reading-and-development).
+
+## Operations and supplied information
+
+| Operation | Purpose | Information to prepare | Completion |
+| --- | --- | --- | --- |
+| `model register` | Establish the project's Model identity | Name, purpose, existing checkout or repository locator, optional source scope | Model ID, descriptor path and revision; local binding details |
+| `model bind` | Locate an existing Model on this host | Model ID and concrete checkout path | Updated host-local binding; existing identity preserved |
+| `model update` | Amend the descriptor | Merge patch and current revision | Updated descriptor and revision |
+| `model retire` | End current use | Current revision, optional reason | Status changed; identity and earlier associations preserved |
+| `model iteration open` | Retain a line of development | Model ID, purpose, starting revision, and the worktree to create or attach, if any | Iteration ID and descriptor; actual branch/worktree if created or attached |
+| `model iteration close` | Retain the development outcome | Iteration ID, expected descriptor revision, outcome, relevant commits and explanation | Updated descriptor and revision; retained refs for each commit |
+| `model iteration remove-worktree` | Remove the iteration's worktree | Iteration ID | The worktree is gone; the iteration descriptor is unchanged |
+
+Registration describes an existing repository. Use ordinary Git for cloning, fetching, and inspecting it. Keep machine-specific checkout paths in local bindings. The portable description may carry a repository locator, but it must remain meaningful when a host has no checkout.
+
+An iteration can attach an existing worktree. If the command creates Git resources, its receipt distinguishes resource creation from descriptor publication. A surviving worktree is useful material even when the metadata write needs recovery.
+
+## Prepare a change
+
+Resolve the intended project, Model, and repository before drafting the input. Read a current descriptor with ordinary tools when its metadata or revision is needed. Use returned IDs rather than relying on names remaining unique after later renames or imports.
+
+```text
+accrete --project PROJECT_ROOT model register --checkout CHECKOUT_PATH --name NAME [--source-scope PATH]
+accrete --project PROJECT_ROOT model register --from INPUT_FILE
+accrete --project PROJECT_ROOT model bind MODEL_ID --checkout CHECKOUT_PATH
+accrete --project PROJECT_ROOT model update MODEL_ID --from PATCH_FILE --expect REVISION
+accrete --project PROJECT_ROOT model retire MODEL_ID --expect REVISION [--from INPUT_FILE]
+accrete --project PROJECT_ROOT model iteration open MODEL_ID --name NAME --purpose TEXT
+accrete --project PROJECT_ROOT model iteration open MODEL_ID --from INPUT_FILE
+accrete --project PROJECT_ROOT model iteration close ITERATION_ID --expect REVISION --from INPUT_FILE
+accrete --project PROJECT_ROOT model iteration close ITERATION_ID --expect REVISION --outcome TEXT --commit COMMIT
+accrete --project PROJECT_ROOT model iteration remove-worktree ITERATION_ID
+```
+
+The capitalized terms are values to supply, not literal paths or IDs. `--project` selects the owning project; `ACCRETE_PROJECT` supplies the same context when no explicit selector is passed. Add global `--json` for machine-readable receipts. The Kernel allocates each managed document's envelope, and an ID unless you supply `--id`; the input files below are drafts for the operation.
+
+A registration draft can describe an existing checkout and optional scope:
+
+```json
+{
+  "name": "atmosphere",
+  "description": "Atmospheric model developed in this project.",
+  "repository": {
+    "checkout": "/work/climate/atmosphere"
+  },
+  "source_scope": ["src", "CMakeLists.txt"]
+}
+```
+
+Replace the example checkout and scope with real values. Omit `source_scope` when it has no useful defined meaning. `repository.checkout` means the same as `--checkout`, and `--checkout` wins if both are given: the Kernel stores it as a host-local binding and leaves it out of the portable descriptor, so the path is not the Model identity. To register without a local checkout, supply `repository.locator` instead and bind later. The Kernel never clones or fetches. Optional `aliases` provides additional project names. `--source-scope` can be repeated.
+
+An iteration-open draft uses the same names as the flags, and flags override: `name`, `purpose`, `branch`, `worktree`, `start`, `existing`, `id`. The Model needs a checkout binding on this host.
+
+```json
+{
+  "name": "transport-order",
+  "purpose": "Investigate the effect of evaluation order in transport.",
+  "branch": "transport-order",
+  "worktree": "/work/climate/iterations/transport-order",
+  "start": "HEAD"
+}
+```
+
+`worktree` creates that worktree from `start` (default `HEAD`). `branch` names a new branch; without it Git creates a detached worktree. `existing: true` attaches a worktree already there, which must belong to the same repository and supplies its own `HEAD`. Without `worktree`, no storage is allocated and the iteration only records the effort.
+
+A close draft has `outcome`, `summary`, and `commits` containing the relevant commit IDs:
+
+```json
+{
+  "outcome": "integrated",
+  "summary": "Merged after the comparison showed the expected reduction in drift.",
+  "commits": ["REPLACE_WITH_COMMIT"]
+}
+```
+
+`outcome` is a free authored string: `integrated`, `retained_separately`, and `abandoned` are illustrative values, not a fixed enumeration. It is required from the file or `--outcome`, and `--commit` can be repeated. Each commit is kept under a local retained ref. Submit the current descriptor `revision` with `--expect`; this token is not a commit ID.
+
+For registration, explain what program the Model denotes and which repository already carries it. If it uses a source scope, say what that scope includes. For a host binding, use the actual checkout path. For an iteration, identify the intended start before allocating work; do not silently treat whichever branch happens to be checked out as the requested start.
+
+For closing, describe what happened and include the relevant end or integration commits when known. Merge or otherwise integrate with Git before reporting that outcome. If the work is retained separately, name its usable branch or commit. If abandoned, preserve the reason when it will help subsequent work.
+
+`remove-worktree` is separate from closing, so a closed iteration can keep its worktree. It removes the path bound to this iteration on this host through Git and keeps Git's refusal to remove changed work; `--force` explicitly asks for Git's destructive removal. Branches stay; delete those with Git.
+
+`model update` takes a JSON Merge Patch. `model retire` takes an optional JSON document whose `reason` is stored on the descriptor. Retirement leaves the repository, checkouts and earlier Results alone.
+
+## Use the mutation response
+
+The shared receipt contract includes `object_id`, `path`, `revision`, `committed`, and `index_pending`, with additional effects where a command changes Git resources or host bindings. Use the returned concrete paths for subsequent native work. The descriptor revision is an optimistic replacement token, distinct from a Git commit.
+
+- A committed descriptor with `index_pending: true` is retained. Continue from its ID; refresh the disposable index when queries need it.
+- A revision conflict means another change intervened. Read the latest descriptor and integrate the intended edit before resubmitting with its revision.
+- A created worktree with incomplete descriptor publication calls for `accrete recover`, which attaches the surviving worktree without repeating development. Preserve the worktree and any edits; do not rerun creation against a different destination.
+- A missing checkout is a binding problem. It does not erase the Model or make a remotely supplied reference meaningless. Repair it with `model bind`.
+- A missing Git executable prevents the Git-dependent operation and exits 5. Restore that dependency or retain the draft for later; a Skill must not implement a replacement lifecycle script.
+
+Read JSON output when automation needs stable fields and keep diagnostics separate from stdout. For retries of creates, supply a stable `--id` or `id` before the first attempt. A retry of object publication does not mean repeating the underlying scientific activity.
+
+## Native reading and development
+
+Use concrete paths supplied by the task, configuration, or receipts:
+
+```sh
+git -C "$model_checkout" status --short
+git -C "$model_checkout" rev-parse HEAD
+git -C "$model_checkout" log -5 --oneline
+git -C "$model_checkout" diff
+git -C "$model_checkout" worktree list
+```
+
+`$model_checkout` is a shell variable set to the actual checkout. Quote it because a valid path may contain spaces. Use `git show`, `git diff`, and native file readers for implementation questions. Query the index with `sqlite3 -readonly` when an object join is useful, at the path in `.local_state.index` from `accrete config resolve --json`. A brief "database is locked" during a concurrent refresh means retry. The index describes retained documents and does not describe a current process or live checkout.
+
+Read a descriptor rather than changing it with `jq` or an editor. Model code, project configuration, instructions, and drafts remain ordinary editable files. Use the Kernel when the intended effect changes Model or iteration organization.