accrete-kit 0.0.0-stage → 0.1.0

package/dist/scaffold/assets/generated/cli-commands.md

@@ -0,0 +1,288 @@
+# CLI command map
+
+Generated from the command catalog of this ACCRETE release. Read
+[CLI semantics](cli-contract.md) for input fields, publication outcomes and
+recovery, and `accrete COMMAND --help` for the same flags at the terminal.
+
+Creating a Workspace and upgrading its template files are not `accrete` commands:
+see [the generator](cli-contract.md#workspace-creation-and-template-upgrades).
+
+Use `--project DIRECTORY` to select the Workspace explicitly and `--json` for receipts.
+Uppercase metavariables must be replaced with actual values. Object arguments
+accept a stable ID, a name or an alias. These flags repeat: `--result`, `--model`,
+`--tool`, `--data` and `--supersedes` on `memory append`, `--commit` on
+`model iteration close`, `--source-scope` on `model register`, `--path` on
+`result capture`, and `--id` on `export`.
+
+## project.migrate.legacy
+
+```sh
+accrete migrate --from LEGACY [--dry-run]
+```
+
+Convert the old scaffold's metadata, retaining original backups and an identity map.
+
+## project.migrate.format
+
+```sh
+accrete migrate [--dry-run]
+```
+
+Handle persisted format changes, keeping identities and relationships. With only format 1 in existence it reports the project is current and changes nothing.
+
+## config.resolve
+
+```sh
+accrete config resolve --json
+```
+
+Report resolved project roots, host, metadata view, state directory and index path without disclosing credentials or writing objects.
+
+## interface
+
+```sh
+accrete interface --json
+```
+
+Report CLI, interface and format versions and exit codes; needs no Workspace.
+
+## model.register
+
+```sh
+accrete model register [--from FILE] [--checkout PATH] [--id ID] [--name NAME] [--description TEXT] [--source-scope PATH]
+```
+
+Allocate a Model identity for an existing Git checkout or a repository locator supplied in JSON. Does not clone or fetch. A checkout becomes a host-local binding.
+
+## model.bind
+
+```sh
+accrete model bind MODEL_ID --checkout PATH
+```
+
+Set this host's checkout binding for a known Model.
+
+## model.update
+
+```sh
+accrete model update MODEL_ID --from FILE --expect REVISION
+```
+
+Amend the Model descriptor; source history stays in Git.
+
+## model.retire
+
+```sh
+accrete model retire MODEL_ID --expect REVISION [--from FILE]
+```
+
+End current use while preserving identity, repository and earlier associations. The optional JSON may carry reason.
+
+## model.iteration.open
+
+```sh
+accrete model iteration open MODEL_ID [--from FILE] [--id ID] [--name NAME] [--purpose TEXT] [--branch BRANCH] [--worktree PATH] [--start REVISION] [--existing]
+```
+
+Describe an iteration. --worktree creates a worktree of the Model's repository unless --existing attaches one; without --worktree no storage is allocated. Flags override --from fields of the same name.
+
+## model.iteration.close
+
+```sh
+accrete model iteration close ITERATION_ID --expect REVISION [--from FILE] [--outcome TEXT] [--commit COMMIT]
+```
+
+Retain the outcome, summary and every selected commit. Outcome is required from the file or --outcome; --commit repeats. Merging and worktree removal stay separate.
+
+## model.iteration.remove-worktree
+
+```sh
+accrete model iteration remove-worktree ITERATION_ID [--force]
+```
+
+Remove the iteration's bound worktree through Git, keeping Git's refusal for changed work unless --force is given.
+
+## tool.admit
+
+```sh
+accrete tool admit [--from FILE] [--id ID] [--name NAME] [--description TEXT] [--source PATH] [--source-mode live|retained] [--revision COMMIT]
+```
+
+Give an existing capability a Tool identity and explicit live or retained source selection.
+
+## tool.bind
+
+```sh
+accrete tool bind TOOL_ID --source PATH
+```
+
+Set this host's source binding for a known Tool.
+
+## tool.update
+
+```sh
+accrete tool update TOOL_ID --from FILE --expect REVISION
+```
+
+Amend metadata or source selection without changing the user's active implementation checkout.
+
+## tool.expose
+
+```sh
+accrete tool expose TOOL_ID --agent codex|claude [--mode wrapper|symlink] [--name NAME] [--destination DIRECTORY]
+```
+
+Create a project-local discovery binding to actual source material; default to a portable source-reading wrapper.
+
+## tool.refresh
+
+```sh
+accrete tool refresh TOOL_ID [--agent codex|claude]
+```
+
+Refresh existing managed exposures, reporting unavailable or pending source material; a retired Tool's local exposures are removed where possible.
+
+## tool.retire
+
+```sh
+accrete tool retire TOOL_ID --expect REVISION [--from FILE]
+```
+
+Retain identity and associations while ending normal discovery; preserve source material and running work. The optional JSON may carry reason.
+
+## tool.export
+
+```sh
+accrete tool export TOOL_ID --to PATH
+```
+
+Create a new local directory with tool.json and source/; external publication remains a separate action.
+
+## data.register
+
+```sh
+accrete data register --from FILE [--id ID] [--name NAME] [--description TEXT] [--result RESULT_ID] [--live]
+```
+
+Describe Data and usable locations without mandatory payload copying, packing or hashing.
+
+## data.register.path
+
+```sh
+accrete data register --path PATH [--id ID] [--name NAME] [--description TEXT] [--kind file|directory|collection|external] [--hash] [--result RESULT_ID] [--live]
+```
+
+Register a local borrowed path in place. --hash computes SHA-256 for one regular file.
+
+## data.amend
+
+```sh
+accrete data amend DATA_ID --from FILE --expect REVISION
+```
+
+Change descriptive metadata. Closed content and the locations array cannot change this way.
+
+## data.location.add
+
+```sh
+accrete data location add DATA_ID [--from FILE] [--location NAME] [--path PATH] [--kind filesystem|rclone|external] [--expect REVISION]
+```
+
+Add a borrowed locator for the same described content; do not redefine earlier Result inputs. A repeated matching location is a no-op.
+
+## data.materialize
+
+```sh
+accrete data materialize DATA_ID [--to LOCATION] [--source SOURCE_LOCATION] [--expect REVISION]
+```
+
+Produce and publish a managed replica at a configured filesystem location (default working) using local transfer or the configured rclone adapter.
+
+## data.evict
+
+```sh
+accrete data evict DATA_ID --location LOCATION [--expect REVISION]
+```
+
+Remove precisely one Kernel-managed replica named by location ID or name, preserving the Data identity and other locations. An ambiguous name is a conflict.
+
+## data.retire
+
+```sh
+accrete data retire DATA_ID --expect REVISION [--from FILE]
+```
+
+End current use while preserving identity, locations and earlier associations; no bytes are removed. The optional JSON may carry reason.
+
+## result.record
+
+```sh
+accrete result record [--from FILE] [--id ID] [--name NAME] [--description TEXT] [--observe-checkout PATH]
+```
+
+Persist a useful activity description and its supplied Model, Tool and Data associations. --observe-checkout adds a separately labelled recording-time observation.
+
+## result.amend
+
+```sh
+accrete result amend RESULT_ID --from FILE --expect REVISION
+```
+
+Apply an explicit correction or enrichment against the actual current document bytes.
+
+## result.observe
+
+```sh
+accrete result observe RESULT_ID --text-file FILE [--operation-id ID]
+```
+
+Append an independent observation to the observations array; an operation ID makes retries unambiguous.
+
+## result.capture
+
+```sh
+accrete result capture --checkout PATH --path SOURCE_PATH --to DIRECTORY
+```
+
+Write a selected binary Git diff and selected nonignored untracked files to a new directory with a manifest of the captured scope. --path repeats. It is not a complete executable environment.
+
+## memory.append
+
+```sh
+accrete memory append --from FILE [--id ID] [--title TITLE] [--authored-at RFC3339] [--result ID] [--model ID] [--tool ID] [--data ID] [--supersedes ID] [--links-from FILE]
+```
+
+Publish complete authored Markdown with a stable ID, timezone-based path and repeatable object links. Retry a lost acknowledgement with the same --id.
+
+## index.refresh
+
+```sh
+accrete index refresh
+```
+
+Refresh the host-local disposable SQLite projection from the selected metadata view.
+
+## export
+
+```sh
+accrete export --to PATH [--id ID]
+```
+
+Write a metadata bundle of selected or all managed documents. Payloads, Git objects, Tool source and machine bindings stay out. --id repeats.
+
+## import
+
+```sh
+accrete import --from PATH [--allow-foreign]
+```
+
+Import a metadata bundle object by object, reporting each outcome. A batch is not atomic; repeating it completes missing entries.
+
+## recover
+
+```sh
+accrete recover [--operation OPERATION_ID]
+```
+
+Reconcile interrupted transfers, evictions, worktree creation and uncertain publications from their receipts. Never relaunches scientific computation. --operation limits Data reconciliation to one operation.
+

package/dist/scaffold/assets/generated/release.json

@@ -0,0 +1,11 @@
+{
+  "template_id": "accrete-foundation",
+  "template_version": "0.1.0",
+  "kernel_version": "0.1.0",
+  "cli_contract": "accrete-template-cli/v1",
+  "project_formats": {
+    "min": 1,
+    "max": 1
+  },
+  "architecture_edition": "2026-11-03"
+}

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

@@ -0,0 +1,73 @@
+---
+name: accrete-data
+description: Retain, locate, materialize, and manage scientific inputs and outputs as ACCRETE Data. Use when a dataset, restart, model output, analysis product, external dataset version, or collection needs a durable identity, a Result association, another replica, or explicit replica eviction. Read available data with native scientific tools.
+---
+
+# ACCRETE Data
+
+Give useful material a continuing project identity when later work needs to
+find it or understand its use. A Data object can describe a file, a directory,
+a collection, or an external dataset version. Its ID denotes the intended
+material; locations say where copies can be accessed. A checksum describes
+bytes within its stated scope. Keep those three meanings separate.
+
+## Choose the appropriate action
+
+| Need | Action |
+| --- | --- |
+| Read an available array, table, or document | Use its normal reader and concrete path. |
+| Produce intermediate outputs or explore a transformation | Work in Scratch or the producer's own directory. |
+| Retain a useful product in place | Call `accrete data register`. |
+| Describe an external dataset before downloading it | Register its locator and known content/version information. |
+| Correct a description | Call `accrete data amend` using the current revision. |
+| Associate an existing additional copy | Call `accrete data location add`. |
+| Obtain a managed usable copy | Call `accrete data materialize`. |
+| Remove one managed copy while preserving its meaning | Call `accrete data evict` for that exact replica. |
+| End current use without removing bytes | Call `accrete data retire`. |
+
+Registration need not copy, archive, upload, traverse, or fully hash a dataset.
+Supply the information already available, and request additional byte work
+only when it serves the task. A Data object may be valid while no copy is
+accessible on the current machine.
+
+## Preserve content meaning
+
+Register a completed product when its relevant writes have finished. When
+working with a live source or open collection, describe it that way. A stable
+path to changing bytes does not identify a historical snapshot. Adding a
+replica or correcting a description changes an existing descriptor; corrected
+scientific content normally receives a new Data ID naming the previous one in
+`replaces`. Keep earlier Results associated with the material they
+actually used.
+
+Use the Result Skill to describe the producing or consuming activity. Link
+Data as an input or output when known; ordinary input/output participation
+does not assert that every output derives from every input. Use Memory for
+interpretation, retention decisions, and lessons that later work should use.
+Keep NetCDF, HDF5, Zarr, Parquet, archives, and domain collections in their
+normal representations. Domain Tools choose transformations and packaging.
+
+## Work through the native boundary
+
+Read shared `.accrete/project.toml` and host-local `.accrete/local.toml` to
+resolve store and location bindings. Paths in examples are illustrative;
+configured paths and mutation receipts identify the actual locations. When
+working outside the ACCRETE root, select it explicitly with `--project`.
+
+Draft registration inputs in ordinary files; publish managed descriptors
+through `accrete`. Use its returned ID and concrete path. If metadata
+was committed but indexing is pending, refresh the index without registering
+another object. If a transfer or eviction stopped partway, run `accrete recover`;
+it finishes from the receipt and reports an incomplete transfer with its paths.
+Metadata repair never requires rerunning the producer.
+
+## Read when needed
+
+- [Objects and native work](references/objects-and-native-work.md): identity,
+  content editions, collections, relationships, and reading existing material.
+- [Command manual](references/commands.md): registration, amendment, retirement,
+  location changes, materialization, eviction, input drafts, and operation outcomes.
+- [Remote work and retention](references/remote-and-retention.md): host
+  placement, scientific outputs, large transfers, and borrowed locations.
+
+`accrete data COMMAND --help` prints the flags.

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

@@ -0,0 +1,193 @@
+# Data command manual
+
+## Contents
+
+- Interface and project selection
+- Register a product in place
+- Draft structured Data input
+- Amend or retire a description
+- Associate another location
+- Materialize a managed replica
+- Evict an exact managed replica
+- Understand operation outcomes
+
+## Interface and project selection
+
+This manual covers the Data commands. `accrete data COMMAND --help` prints the flags.
+
+Global options are `--project DIRECTORY` and `--json`. `ACCRETE_PROJECT` can select
+the project when no explicit `--project` is present. Otherwise the Kernel finds
+the nearest project marker from the current directory. Invocation selection
+takes precedence over the environment. Relative shared and local configured
+paths resolve against the selected project root.
+
+The full contract is installed at project-root path
+`.accrete/docs/cli-contract.md`; the generated command map is at
+`.accrete/docs/cli-commands.md`. JSON output goes to stdout and diagnostics to
+stderr. Use returned paths and IDs instead of deriving filenames yourself.
+
+## Register a product in place
+
+After a producer has closed a directory selected for retention:
+
+```sh
+accrete --json data register --name year-1-output \
+  --path /scratch/project-a/run/year-1/output \
+  --kind directory --result "$RESULT_ID"
+```
+
+`RESULT_ID` denotes the actual producing Result when known. Omit `--result`
+when no Result exists or the relationship is unknown. The command establishes
+a Data identity and a borrowed location. Registration does not copy the
+directory or imply permission to delete it. A local path may be outside the
+project root. A relative `--path` resolves from the project root, and a symlink
+is refused.
+
+Registration is metadata-proportional by default. `--hash` computes SHA-256 for
+one regular file; directories can refer to a producer-owned manifest. Recursive
+inventory, archiving, and upload are separate explicit choices. Do not request
+them merely to make a descriptor look complete. `--live` describes mutable
+material, and `--id` gives a stable ID for retries.
+
+## Draft structured Data input
+
+Use a structured draft for richer content and locations:
+
+```sh
+accrete --json data register --from scratch/data.json
+```
+
+The following is a complete example of the input fields. Replace its example
+path and host with actual configured context before use. The Kernel assigns the
+object envelope, and a UUID unless you supply `id`.
+
+```json
+{
+  "name": "year-1-diagnostics",
+  "description": "Selected diagnostics from the completed first simulation year.",
+  "content": {
+    "kind": "directory",
+    "mode": "closed",
+    "format": "NetCDF collection"
+  },
+  "origin": {
+    "description": "Produced by the first-year simulation; selection preserved by the domain launcher."
+  },
+  "locations": [
+    {
+      "name": "compute-output",
+      "kind": "filesystem",
+      "host": "gpu-a",
+      "path": "/scratch/project-a/year-1/diagnostics",
+      "managed": false
+    }
+  ]
+}
+```
+
+Draft fields:
+
+| Field | Meaning |
+| --- | --- |
+| `name`, `description` | Human organization and intended material. |
+| `content.kind` | `file`, `directory`, `collection`, or `external`. Without `--path` it defaults to `external`. |
+| `content.mode` | `closed` (the default) for an intended fixed edition; `live` for changing content. |
+| `content.format` | Optional native format description. |
+| `content.edition` | Optional words describing the intended edition, such as a provider's release name. |
+| `content.size_bytes` | Optional known size. Materialization checks it for a file. |
+| `content.sha256` | Optional SHA-256 of a regular file's bytes. Materialization checks it. |
+| `origin.description` | How the material arose. |
+| `origin.result_id`, `origin.uri` | Optional producing activity or provider location. |
+| `replaces` | Optional earlier Data ID that this corrected edition replaces. |
+| `locations` | Access locations, each with its own generated ID. |
+| `locations[].name` | Optional. A configured location name supplies its kind and root or remote. |
+| `locations[].kind` | `filesystem`, configured `rclone`, or `external` for a locator the Kernel records and never transfers. |
+| `locations[].host` | Host context for a physical path; filesystem locations default to the current host. |
+| `locations[].path` | Filesystem path, backend-relative path, or external locator. |
+| `locations[].managed` | `false` or omitted; `true` is refused. The Kernel sets managed ownership for replicas it creates. |
+
+A location is a usable locator; an origin explanation alone is insufficient for
+materialization. An external version can be registered without downloading it.
+Do not add a `sha256` whose bytes have not been hashed. A backend `version`,
+`version_id` or `s3_version_at` on a location is kept as an opaque token, and
+`data materialize` refuses a source that carries one rather than silently
+fetching current bytes. Use a version-specific exported locator, or retrieve
+that version with the provider's tool and register the local copy.
+
+## Amend or retire a description
+
+```sh
+accrete --json data amend "$DATA_ID" --from scratch/change.json --expect "$REVISION"
+accrete --json data retire "$DATA_ID" --expect "$REVISION"
+```
+
+`data amend` takes a JSON Merge Patch of descriptive fields. It refuses to change
+closed `content` or replace `locations`; those need a new Data ID or the location
+commands below. `data retire` changes status and removes no bytes. Its optional
+`--from FILE` document can carry a `reason`, stored on the descriptor.
+
+## Associate another location
+
+When a known copy already exists at a configured location:
+
+```sh
+accrete --json data location add "$DATA_ID" \
+  --location archive --path retained/year-1
+```
+
+`--location` names the location, `--kind filesystem|rclone|external` overrides its
+kind, and `--from FILE` accepts the same fields as JSON. `--expect REVISION` is
+optional. A path relative to a configured filesystem root resolves there. A
+repeated matching location is a no-op. The command records an association. It does
+not perform the transfer, rewrite content identity, or turn a borrowed path into a
+Kernel-owned replica. Keep backend credentials in native configuration.
+
+## Materialize a managed replica
+
+```sh
+accrete --json data materialize "$DATA_ID" --to working
+```
+
+`--to` is a configured filesystem location name, by default `working`. The command
+selects a usable source, stages the transfer, publishes the completed replica at
+`ROOT/DATA_ID/REPLICA_UUID/payload`, then records its location. The receipt supplies
+the path to read with ordinary scientific tools and names the content checks actually
+performed. If the source is ambiguous, select it with `--source LOCATION_ID` or an
+unambiguous name. `--expect REVISION` ensures the descriptor has not changed first.
+
+A repeat can return an existing present replica at the same root. Partial transfer
+bytes remain separate from published usable material. Symlinks and special files are
+refused; package them first. For a project already using DVC or DataLad,
+materialization through those native tools can be followed by `data location add`
+for the obtained copy.
+
+## Evict an exact managed replica
+
+```sh
+accrete --json data evict "$DATA_ID" --location "$LOCATION_ID"
+```
+
+`--location` takes the location's ID or name; an ambiguous name is a conflict. Choose
+the exact recorded managed location after deciding that removing this copy serves the
+task. The Kernel removes that managed replica and updates its availability while
+preserving the Data identity and Result associations. Borrowed paths are not eligible
+merely because they were registered. The other recorded locations can inform retention
+decisions; their availability may be dated, and local metadata does not describe all
+external uses.
+
+## Understand operation outcomes
+
+| Outcome | Meaning and next action |
+| --- | --- |
+| `committed: true`, `index_pending: false` | The document was published and the local projection updated. Use its ID/path. |
+| `committed: true`, `index_pending: true` | The document exists. Run `accrete index refresh` to repair the projection. |
+| `published: true`, uncertain durability (exit 8) | The destination is visible; run `accrete recover`. Do not allocate a replacement identity. |
+| Conflict before publication (exit 4) | Retain the current descriptor and input draft; resolve the specific differing content or binding. |
+| Transfer side effect with descriptor pending (exit 7) | Run `accrete recover`, or `accrete recover --operation OPERATION_ID` for one operation. |
+
+`accrete recover` finishes publishing a completed transfer or eviction from its
+receipt. A receipt for an incomplete transfer is reported with its paths and left for
+explicit retry or cleanup; recovery does not start the transfer again. A retry of the
+same persistent operation must not change into a new Data object or a second scientific
+execution. Data registration and a subsequent Result update can complete separately;
+finish the missing association without undoing the already-retained product.

package/dist/scaffold/assets/skills/accrete-data/references/objects-and-native-work.md

@@ -0,0 +1,123 @@
+# Data objects and native work
+
+## Contents
+
+- Identity and content
+- Choosing what to retain
+- Collections and scientific representations
+- Relations to other objects
+- Reading and changing material
+
+## Identity and content
+
+Keep these descriptions distinct when interpreting a Data descriptor:
+
+| Description | Meaning |
+| --- | --- |
+| Stable ID | The project object meant by later links. |
+| Name or alias | A readable label that may change. |
+| Content description | The intended file, collection, provider edition, or live source. |
+| Origin | How the material arose: provider, extraction, generating Result, or explanation. |
+| Location | A concrete filesystem or backend locator through which bytes may be accessed. |
+| Availability observation | What was known about a location at a particular time. |
+| `content.sha256` or manifest | Optional identification of a file's bytes or of explicitly scoped content. |
+| Descriptor revision | The current metadata bytes used to detect conflicting edits. |
+
+Two Data IDs may intentionally denote different products with identical bytes.
+Storage deduplication does not merge their identities. Conversely, a path may
+keep its spelling while its contents change. Naming a live path alone does
+not identify what a historical activity consumed.
+
+A closed object describes one intended content edition. Add locations and
+correct metadata without changing that edition. If a numerical fix produces
+different output, register a new object and relate it to the previous one.
+A provider-native immutable version can identify an edition, described in
+`content.edition`. Keep opaque backend tokens as supplied; an mtime or ETag is not a
+SHA-256 content digest, and a backend version selector is not something generic
+materialization will fetch.
+
+The revision returned after a descriptor amendment serves optimistic editing.
+It is separate from the content identity: adding an archive copy changes the
+descriptor while leaving the scientific product unchanged.
+
+## Choosing what to retain
+
+Retain material that gives subsequent work something useful to reuse, inspect,
+compare, or cite. A small diagnostic table may deserve a stable identity while
+large regenerable intermediates remain Scratch. Existing provider data may
+need an identity before any download. Compiler caches can remain ordinary
+performance aids without becoming scientific Data.
+
+No fixed size threshold, retention duration, or sequence of registration steps
+applies to every project. Choose the smallest useful description. Examples of
+reasonable choices include:
+
+- Register an existing restart directory in place after the producer closes it.
+- Register a provider's immutable dataset version and its remote locator.
+- Preserve selected variables from a large simulation through a domain Tool,
+  then register the selected product as new Data linked to its generating Result.
+- Leave an exploratory plot in Scratch until it is useful to retain.
+- Describe a mutable observational feed explicitly as live, with the version
+  or extraction used by a particular Result when available.
+
+Neither registration nor an archive locator proves that restoration will be
+possible indefinitely. Availability descriptions are dated observations.
+
+## Collections and scientific representations
+
+A directory, a manifest-defined set, and a provider dataset version are useful
+forms of Data. Preserve their native reading behavior. A Zarr collection need
+not be converted into a tarball, and its chunks need not each become ACCRETE
+objects. A domain reader understands array metadata and calendars; the Kernel
+understands identity and location.
+
+For output produced in stages, retain completed products independently when
+useful. A multiyear simulation might produce one retained restart and one
+diagnostic collection per completed year. A parent collection may link them;
+the project need not adopt a universal Year/Run/Experiment hierarchy.
+
+An open collection can acquire membership observations. A Result requiring
+a fixed membership must identify the edition or manifest it used. Merely
+adding a later partition to a changing directory does not retrospectively
+change the set consumed by an earlier analysis.
+
+The producer remains responsible for safe concurrent reading and completion
+of its format. Registering a partly written HDF5 file cannot make it a usable
+snapshot. Follow the scientific program's closure, flush, or snapshot behavior.
+
+## Relations to other objects
+
+Use Result input and output links to preserve how Data participated in an
+activity. Data origin can name a generating Result where useful. A Model
+describes the program; a Result describes a particular use of that program;
+Data describes retained material. A Tool may perform extraction, comparison,
+transfer preparation, or format conversion. Memory explains what the material
+means for later decisions.
+
+Keep supplied roles such as `initial_state`, `forcing`, `restart`, or
+`diagnostics` as domain descriptions. They are not globally fixed Data classes.
+Cross-host relations may be unresolved locally until their documents arrive.
+Do not download a dataset merely to make its ID locally resolvable.
+
+## Reading and changing material
+
+Read small descriptors with ordinary file tools, and read content with the
+appropriate scientific software. For default roots, useful starting points are:
+
+```sh
+rg 'restart|forcing|diagnostic' .accrete/objects
+jq '.' /path/from/a/data-receipt.json
+```
+
+Replace the example path with the actual descriptor path. Use `sqlite3
+-readonly` on the host-local index, at the path in `.local_state.index` from `accrete
+config resolve --json`, for relational questions, after checking that its projection
+covers the documents needed. Use native SQL schema discovery (`.schema`) instead of
+assuming a column. A brief "database is locked" during a concurrent refresh means retry. `accrete index refresh` rebuilds a stale projection from small
+documents; it does not reprocess scientific payloads.
+
+Edit scientific source or working content with ordinary tools. Publish Data
+registration and location changes with the Kernel. If directly editing managed
+metadata is explicitly required, coordinate with other writers and run `accrete index
+refresh` afterward. A direct file edit does not participate in the Kernel's local
+concurrency protection.