accrete-kit 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,87 @@
+# Tool Kernel operations
+
+This manual covers the Tool commands. `.accrete/docs/cli-contract.md` has the shared conventions and `accrete tool COMMAND --help` prints the flags.
+
+Contents: [lifecycle](#operations), [source drafts](#prepare-source-and-input-drafts), [exposure](#expose-and-refresh), [retirement and export](#retire-or-export), [responses](#use-the-response).
+
+## Operations
+
+| Command | Durable effect | Work the Agent does with ordinary tools |
+| --- | --- | --- |
+| `tool admit` | Allocate a Tool ID and associate existing capability source | Develop the source and decide that it is useful to retain |
+| `tool bind` | Set this host's source location for a known Tool | Obtain the source on this host |
+| `tool update` | Amend descriptor metadata or select a source form or revision | Edit and commit implementation and knowledge |
+| `tool expose` | Add a selected agent discovery interface | Choose whether automatic discovery helps |
+| `tool refresh` | Reconcile existing managed discovery with the selected source and descriptor | Supply usable material and communicate consequential changes |
+| `tool retire` | Mark current use retired and reconcile local managed exposures | Decide how the capability should evolve |
+| `tool export` | Produce an explicit local export | Choose subsequent transport or publication |
+
+All commands accept explicit project context through global `--project`; `ACCRETE_PROJECT` is the environment fallback. Use global `--json` when a caller needs structured mutation receipts. No operation requires a separate `tool create` stage or an admission evaluation.
+
+## Prepare source and input drafts
+
+Admit source that already exists, with flags or a draft written with an ordinary editor in Scratch:
+
+```json
+{
+  "name": "transport-diagnostics",
+  "description": "Compute and interpret transport diagnostics for the project's atmospheric model.",
+  "source": {
+    "path": "tools/transport-diagnostics",
+    "mode": "live"
+  }
+}
+```
+
+The example path is relative to the owning project. Replace it with the real source location; do not create a fake program merely to satisfy the draft. Source may be executable or cognitive. The Kernel allocates the Tool's document envelope, and an ID unless you supply `--id`.
+
+```text
+accrete --project PROJECT_ROOT tool admit --from INPUT_FILE
+accrete --project PROJECT_ROOT tool admit --name NAME --description TEXT --source SOURCE_DIRECTORY
+accrete --project PROJECT_ROOT tool bind TOOL_ID --source SOURCE_DIRECTORY
+accrete --project PROJECT_ROOT tool update TOOL_ID --from PATCH_FILE --expect REVISION
+```
+
+A source outside the project becomes a host-local binding rather than a portable path. On another host, obtain the source natively and run `tool bind`; an absent source is a binding to repair, not a reason to retire the Tool.
+
+`tool update` accepts a JSON Merge Patch of the editable descriptor fields. Supply the current descriptor revision as `--expect`. Preserve unfamiliar fields by changing only the intended fields. An update can amend description or choose a new source; it does not edit, commit, or switch the actual source repository.
+
+For a retained source, use `source.mode: "retained"`, a source commit in `source.revision`, and `source.path` naming usable material at that revision, or `--source-mode retained --revision COMMIT`. Prepare the corresponding checkout or export before attempting exposure; exposure requires a clean checkout at that commit, and `tool bind` can point this host at one. A live source can also carry a revision observation; that historical observation does not freeze subsequent edits.
+
+## Expose and refresh
+
+```text
+accrete --project PROJECT_ROOT tool expose TOOL_ID --agent codex
+accrete --project PROJECT_ROOT tool expose TOOL_ID --agent claude
+accrete --project PROJECT_ROOT tool refresh TOOL_ID
+accrete --project PROJECT_ROOT tool refresh TOOL_ID --agent codex
+```
+
+`--agent` chooses the discovery interface. The global `--host` is a different thing: it labels the machine. Exposure defaults to a portable wrapper. Use `--name NAME` when a distinct discovery name is needed (lowercase letters, digits and single hyphens, up to 64 characters) and `--mode symlink` only when deliberately selecting a direct link, which needs Unix and a source `SKILL.md` whose frontmatter `name` matches the exposure and whose `description` is nonempty. `--mode wrapper` requests the default explicitly. The exposure mechanism is independent of `source.mode`.
+
+The Codex discovery destination is under `.agents/skills/`; Claude's is under `.claude/skills/`. `--destination DIRECTORY` selects another location, and the operation receipt names the exact path. `tool expose` excludes a generated exposure from Git through the repository-local `.git/info/exclude`, because a wrapper can hold this host's absolute source path. A generated wrapper is a valid Skill with a useful name, description, and a pointer to the complete source instructions. It says that references and executable paths resolve from the source directory.
+
+Edit the source rather than a generated wrapper. After changing discovery-relevant content or a local source binding, refresh the affected managed interfaces. If there is no source Skill or equivalent usable guidance, continue using the Tool directly or develop that guidance before asking for discovery. An executable can remain a valid Tool without an exposure.
+
+If the destination is occupied by unrelated or edited content, it is preserved and reported as a conflict. Choose another `--name` or `--destination`, or clear the destination yourself if the owner wants it replaced. Source absence or unavailable retained material leaves that exposure pending. Read the receipt to distinguish a retained Tool from an installed agent interface.
+
+## Retire or export
+
+```text
+accrete --project PROJECT_ROOT tool retire TOOL_ID --expect REVISION [--from INPUT_FILE]
+accrete --project PROJECT_ROOT tool export TOOL_ID --to DESTINATION
+```
+
+`--from` is optional. A document such as `{"reason":"Superseded by the project's current transport diagnostic."}` stores its `reason` on the descriptor. Submit the latest descriptor revision.
+
+Retirement preserves the source and earlier associations. It removes managed discovery on the invoking host; other hosts run `tool refresh` after receiving the shared change. A running activity can finish using its already selected implementation. Do not remove source files or process state merely because the descriptor is retired.
+
+Export writes a new local directory containing `tool.json` and `source/`. It omits Git internals and refuses symlinks whose transfer meaning needs an explicit choice, and an existing destination is a conflict. It does not publish a registry package or push a repository. Use the user's chosen native publishing method for any later distribution.
+
+## Use the response
+
+Read `object_id`, `path`, `revision`, and `committed` from the shared mutation receipt, plus each reported exposure or export effect. `index_pending` signals a delayed local projection, not loss of the primary descriptor. Admission and exposure have separate completion points: a Tool can exist while one agent interface remains pending.
+
+For revision conflicts, read the latest descriptor and integrate the requested change before retrying. For lost acknowledgments on creation, supply a stable `--id` before the first attempt and repeat with the same ID; do not admit duplicate identities by guessing whether the previous write completed. If durability is reported uncertain, run `accrete recover`.
+
+Read Tool source and descriptors with native file tools and Git. Use the actual implementation's executable directly. If a domain script also retains a Result or Data object, it calls the CLI and consumes receipts. Foundational Skill references never replace these operations with their own persistence scripts.

package/dist/scaffold/assets/skills/accrete-tools/references/objects.md

@@ -0,0 +1,66 @@
+# Tool meaning and relationships
+
+## Capability, Tool, and Skill
+
+| Term | Meaning | Useful consequence |
+| --- | --- | --- |
+| Capability | An ability to understand or do something | Can combine executable methods and explanatory knowledge |
+| Tool | The retained project object through which the capability is named and maintained | Has a stable ID, source association, evolving description, and lifecycle |
+| Skill | A host interface that lets an Agent discover and load the capability | Can expose an existing Tool without becoming its identity |
+
+A numerical diagnostic can combine scripts, data conventions, plots, and interpretation notes. A guide to diagnosing model output can be entirely cognitive. A compiled program can remain directly callable while a small Skill explains its role. The project chooses the material that makes the ability reusable.
+
+An experimental file does not need immediate admission. It becomes a Tool when preserving its identity and use is helpful. Source can remain in the project Git repository, an independently versioned repository, or an external directory. One repository per Tool is unnecessary.
+
+The Tool ID remains stable when a capability changes its name, location, source revision, or host exposure. Several exposures can refer to the same Tool. A host-generated path is a locator; it must not become the identity used in Results.
+
+## Source history and use
+
+The Tool's source can include code, documentation, configuration, and reference material. Use ordinary editing and Git for that content. A descriptor identifies its purpose and source. Updating that descriptor is separate from editing source; refreshing discovery is separate again.
+
+A Result can identify the Tool even when it was used directly by a program or read by path. Record its observed implementation when available. For a Tool embedded in a larger repository, a commit gives a historical address and an optional scoped tree identity can explain whether the Tool's own content changed.
+
+A source commit alone may not identify a compiled binary or an interpreter's imported code. Supply the actual artifact, entry point, and runtime information when the launcher knows them. Unknown information can remain absent. Reconstructing an activity later from the latest Tool descriptor can incorrectly assign an implementation that was never used.
+
+## Live and retained bindings
+
+| Binding | Meaning | What makes the exposure usable |
+| --- | --- | --- |
+| Live | Follow the named editable source | The source exists and its current operating instructions can be read |
+| Retained | Use material corresponding to a deliberately selected revision | A caller-supplied checkout or artifact actually matches that selection |
+
+A live binding can improve during a project. Its admission-time commit remains historical context. The next activity must describe the implementation it actually uses. A changed source description may require refreshing the host wrapper; a direct source link can make edits visible immediately, subject to the host's loading behavior.
+
+A retained selection needs concrete material. Prepare a dedicated checkout or exported artifact through native tools and associate that location. The Kernel must not change the user's active branch to make an exposure resemble a selected historical commit. If matching material is absent, retain the descriptor and report the pending binding.
+
+Do not treat these source modes as the exposure mechanism. `wrapper` and `symlink` describe how a host discovers a Tool; `live` and `retained` describe what implementation that discovery refers to.
+
+## Host exposure
+
+The portable exposure is an ordinary directory with a valid `SKILL.md`. A generated wrapper describes the capability and names the complete source Skill and source directory. The Agent reads those source instructions before using it. Relative references and program paths belong to the source directory.
+
+An explicit symlink can expose the source where supported. A Tool that relies on host-specific substitutions may need a matching adapter or direct link. Keep such host behavior in the adapter or source instructions that explain it; the Tool's meaning can remain independent of a particular Agent host.
+
+Expose project capabilities only at the selected project destination unless the user explicitly chooses another destination. A name collision is reported as a conflict and resolved by a different `--name` or `--destination`. Existing unrelated Skills and home-directory configuration are not part of Tool admission.
+
+Machine-specific absolute source bindings normally stay out of shared Git content. A clone retains the Tool descriptor and sets its own local source with `tool bind` before exposure. Unavailable source on one machine does not retire a capability useful elsewhere.
+
+## Export and retirement
+
+Export produces a new directory at an explicit destination, containing `tool.json` and `source/`. It can be transferred through Git, npm, a host plugin, or ordinary file transport when the user chooses. Export is a local packaging action and does not imply public publication or installation in another user's environment.
+
+Retirement changes the shared descriptor's current availability and removes or disables exposures managed on the invoking host. It preserves source files and earlier Result references. Other hosts reconcile local exposure after receiving the descriptor and explicitly refreshing it. Retirement cannot erase instructions already loaded in a running conversation or stop an executing program.
+
+If a capability has been replaced, explain the relationship in its description or later Memory. Earlier activities remain associated with the implementation they used. A new capability can deserve a new identity; an improved implementation of the same purpose can evolve under the existing identity. Make that judgment from project meaning.
+
+## Relationships and independent evolution
+
+| Association | Meaning |
+| --- | --- |
+| Tool source and revision | The maintained implementation and knowledge |
+| Tool host exposure | A discovery interface on a specific host |
+| Result uses Tool | A capability participated in the retained activity |
+| Tool operates on Model or Data | Domain instructions explain applicable objects and material |
+| Memory explains Tool experience | Lessons, interpretation, and directions for later improvement |
+
+Foundational ACCRETE Skills are installed by `accrete-kit` and refreshed explicitly with `npx accrete-kit@latest upgrade`. Domain Tools evolve according to the project's needs. A Tool declares a Kernel requirement when it invokes Kernel operations; an ordinary plotting capability does not need a new version whenever ACCRETE receives a patch release.

package/dist/scaffold/assets/skills/accrete-tools/references/working-practice.md

@@ -0,0 +1,51 @@
+# Developing useful project capabilities
+
+## Retain the part that helps future work
+
+A capability often begins during a concrete task: a diagnostic script, a useful interpretation method, a data conversion, or knowledge of a remote environment. Keep exploration flexible. Admit the source when its purpose, implementation, and usage knowledge are valuable to preserve under a project identity.
+
+Choose source organization for the work. A small script and its instructions can share a directory in the project. An independently developed numerical utility can remain in its own repository. A cognitive Tool can consist entirely of Markdown. The Kernel needs enough source association to retain and expose the capability; it does not choose the implementation language or development method.
+
+Use Scratch for incomplete work. Once admitted, the source remains ordinarily editable. A local improvement need not generate a new Tool ID, a new host exposure, and a new Result automatically. Retain the organizational changes that the project's continuation actually needs.
+
+## Write instructions an Agent can use
+
+Explain the capability's object and purpose in concrete terms. State which Model, Data, file format, or interpretation problem it applies to. Describe the useful action and the meaning of its outputs. Include the environment and source-relative paths that another worker needs, and identify known limits of the method at their relevant scope.
+
+For a Skill interface, put its main trigger in frontmatter `description` and the essential action in `SKILL.md`. Keep detailed command use, input conventions, or scientific interpretation in clearly linked references. Load those references only when the current task needs them. A program's own `--help` can document argument syntax while the Skill explains when the program is useful and what its result means.
+
+Domain scripts may perform substantial computation and may call the native ACCRETE CLI to retain their outputs. Keep all object creation, amendment, host exposure, and Memory publication in that CLI boundary. Writing NetCDF, preparing a temporary report, or editing a program remains ordinary work.
+
+Avoid converting research into one mandatory sequence. A Tool may help one part of an investigation and leave the next step to the Agent. State assumptions that matter; do not add a required assessment or approval state merely to admit or use the capability.
+
+## Preserve source-relative meaning
+
+A wrapper might be installed at `.agents/skills/transport-diagnostics/SKILL.md` while source lives at `tools/transport-diagnostics/`. When its source Skill refers to `references/interpretation.md` or `scripts/diagnose.py`, resolve those paths from `tools/transport-diagnostics/`.
+
+Read the complete source Skill before following its supporting references. Edit that source. Refresh the generated wrapper when its discovery description or binding changes. The wrapper is a discovery interface, so keeping independent editable copies of its implementation there would make future changes ambiguous.
+
+Foundational ACCRETE Skills follow a different packaging arrangement: their small release snapshots are copied as real directories into each enabled host discovery path. Their references travel with each copy. Domain Tools retain their own source and use a wrapper or explicitly chosen direct link.
+
+## Describe live changes and retained versions
+
+With a live binding, ordinary source edits become the next usable implementation. Record the actual source used by an activity when known. If another worker is already running an earlier implementation, name the change in a handover and let that activity remain associated with its earlier source.
+
+With a retained binding, prepare material at the selected revision. A dedicated detached worktree or exported artifact can carry it without disrupting active development. A descriptor that names an old commit does not itself produce that material. Pending exposure is the honest result when it is unavailable.
+
+For a compiled Tool, keep its source revision and actual artifact identity distinct when those matter. For an interpreted Tool, capture the entry point and environment the launcher actually selected. Retrospective registration should use available execution information and retain unknowns, rather than borrow the latest descriptor revision.
+
+## Use results and experience to evolve the capability
+
+A Result retains a meaningful activity and the Tool implementation that participated. Data retains selected outputs or source artifacts. Memory explains the interpretation, a discarded approach, or a lesson for subsequent work. Put stable operating knowledge back into the Tool when it will help future users.
+
+For example, a long-running analysis may reveal that one diagnostic is sensitive to a dataset's calendar convention. A later Memory entry can explain that finding in the scope of its observations. Improving the Tool's instructions or implementation helps future use. Earlier Results remain associated with the method and conditions used at the time.
+
+Trust earlier retained work within its described scope. A new question, changed input semantics, or a changed implementation can motivate new work. A Kernel update or a host wrapper refresh alone does not require repeating the scientific activity.
+
+## Work across hosts and share deliberately
+
+Carry shared source and descriptor changes through ordinary version control. Set concrete machine bindings with `tool bind` and run `tool refresh` on each host that needs it. If a source directory is temporarily absent on one machine, the Tool remains part of the project. Use it where the material is available or restore the binding when needed.
+
+The CLI reports which interfaces it refreshed. A running Agent can still have earlier instructions in context; subsequent work can read the new source explicitly or use the host's documented refresh behavior. Discovery changes do not replace a running program or retrospectively change an activity.
+
+Export to a new local directory with `tool export` when another project should reuse the capability; it writes `tool.json` and `source/`. Review the contents as ordinary packaging work, and keep host-specific absolute paths out of portable guidance. Public distribution remains the user's chosen Git, npm, or plugin action. `tool.json` lets the receiving project understand how its capability relates to the original.

package/dist/scaffold/assets/template/.accrete/PROJECT.md

@@ -0,0 +1,31 @@
+# Project context
+
+This file belongs to the project. Workspace creation writes it once; template
+upgrades preserve it. Keep it concise and edit it as the work develops.
+
+## Purpose and current direction
+
+Use the owner's current request to determine the objective, scope, and useful
+deliverable. Preserve consequential choices and remaining questions in project
+Memory when they will help later work. Add a standing project purpose here when
+one has been established.
+
+## Working preferences
+
+Use native development and scientific tools. Choose direct work or delegation
+according to the task. Retain useful code, capabilities, data descriptions, and
+interpretations without making every temporary action a managed object.
+
+## Machines and resources
+
+Resolve host paths through `.accrete/local.toml` and domain Tool instructions.
+Place current machine restrictions, resource allocations, and environment
+conventions here when they are relevant. The template imposes no GPU assignment,
+worker count, model family, interpreter, or scientific package version.
+
+## Retention and continuation
+
+Keep the material needed to continue useful work. Prefer referring to existing
+Results and Memory over repeating an activity merely to reconfirm it. Describe
+changed assumptions explicitly. Before removing a temporary worktree or run
+directory, retain the selected products that future work will use.

package/dist/scaffold/assets/template/.accrete/config-examples/local-compute.toml.example

@@ -0,0 +1,27 @@
+# Compute-host example; adapt this host's actual paths and project aliases.
+# local_state.base must be local even when project metadata is on NFS/Lustre.
+host = "gpu-a"
+
+[local_state]
+base = "/local/project-name/accrete-state"
+
+[paths]
+scratch = "/scratch/project-name/run"
+
+[models.target]
+checkout = "/home/project-name/checkouts/target"
+
+[models.reference]
+checkout = "/home/project-name/checkouts/reference"
+
+[locations.working]
+root = "/scratch/project-name/data"
+
+[locations.archive]
+remote = "project-archive"
+prefix = "project-name"
+
+# An interpreter binding describes a project-managed environment; it does not
+# cause ACCRETE to create or activate it.
+# [environments.jax-gpu]
+# python = "/home/project-name/envs/jax-current/bin/python"

package/dist/scaffold/assets/template/.accrete/config-examples/local-workstation.toml.example

@@ -0,0 +1,21 @@
+# Host-local example; adapt paths and aliases, then save as .accrete/local.toml.
+# All paths shown here are illustrative and must name this machine's locations.
+host = "workstation"
+
+[local_state]
+base = "/absolute/host-local/accrete-state"
+
+[paths]
+scratch = "scratch"
+
+# Bind only aliases for Models already registered in this project.
+# [models.target]
+# checkout = "/absolute/checkouts/target"
+
+[locations.working]
+root = "/absolute/retained-products"
+
+# Native tool credentials remain in their native configuration.
+# [locations.archive]
+# remote = "project-archive"
+# prefix = "project-name"

package/dist/scaffold/assets/template/.accrete/config-examples/project.toml.example

@@ -0,0 +1,27 @@
+# Shared project configuration example. This is not an initialized project.
+# `npx accrete-kit@latest create` generates project_id; preserve it in every clone.
+# See ../docs/configuration.md.
+format = 1
+project_id = "GENERATED_AT_WORKSPACE_CREATION"
+name = "project-name"
+timezone = "UTC"
+
+[paths]
+metadata = ".accrete/objects"
+results = "results"
+memory = "memory"
+tool_sources = "tools"
+scratch = "scratch"
+
+[locations.working]
+kind = "filesystem"
+purpose = "Current scientific products retained in place"
+
+[locations.archive]
+kind = "rclone"
+purpose = "Selected retained products"
+
+# Add environment guidance only for an existing project capability.
+# [environments.jax-gpu]
+# description = "Project-maintained execution environment"
+# instructions = "tools/model-execution/references/environment.md"