--- name: artifact-yylo description: Capture and retrieve durable YYLO Ledger artifact Records with intentional profiles, payload modes, provenance, retention, and secret-safe immutable evidence. argument-hint: "[artifact or evidence to capture/find/inspect]" enable-shell-directives: true --- # Use YYLO artifact Records Treat Ledger as the source of truth for artifact identity and metadata. Use `yy ledger` in a YYLO controller or `yylo-ledger` standalone. Inspect `COMMAND artifact --help`; if unavailable, do not create store files manually. A Ledger Artifact Record is durable evidence, not an npm/Python release artifact and not an implicit request to publish or deploy. ## Classify before capture Choose the profile matching the evidence: - `stdout`: bounded process output; - `model-output`: an agent/model response; - `report`: a generated human- or machine-readable result; - `receipt`: evidence binding an operation and its inputs/outcome. Choose payload mode deliberately: - `inline`: small immutable bytes embedded in the Record; - `local`: immutable content-addressed bytes in Ledger storage; - `external`: immutable external bytes with URI, digest, and size; - `link`: URI reference without an immutable-byte guarantee. Prefer immutable evidence when later verification depends on exact bytes. A link must never be presented as content-addressed proof. ## Create explicitly Use file/stdin transport and provide the media type: ```bash yy ledger artifact create --title "Focused test report" --profile report \ --mode local --media-type application/json --file report.json ``` For external immutable content, provide the supported URI, SHA-256 digest, and size shown by installed help. Never embed URI credentials. Ledger rejects unsafe schemes, traversal, size/digest mismatches, oversized capture, and known secret patterns. Attach only supported, non-secret provenance such as actor, agent, model, session, run, invocation, task, or workflow identity. Task/workflow provenance uses immutable Record IDs. Select `temporary`, `standard`, or `permanent` retention deliberately; retention metadata does not itself authorize deletion. ## Operational-document boundary Store new PDRs, architecture and migration contracts, plans, reports, receipts, and execution evidence as Artifact Records. Draft through a fresh external file, capture it with an intentional profile and immutable payload mode, read it back, and verify its ID, digest, size, provenance, retention, and history before removing the draft. Use the `report` profile for human-readable PDRs/contracts unless installed help provides a more specific approved profile. Product `docs/` is only for documentation shipped as part of the product. Never put operational evidence there to manufacture a task product diff. Preserve legacy `.juno_task/specs` files, but do not create new ones as a fallback. If the installed artifact API is unavailable, stop with the external draft intact and request a Ledger upgrade; do not put it in task bodies, responses, product docs, or manually managed controller paths. ## Find and verify Preflight `yy ledger get --help`; prefer `yy ledger get RECORD_ID -f json` for any known ID without guessing its kind. If installed get is task-only, use `yy ledger record get RECORD_ID -f json` after checking native help; stop for an upgrade if unavailable. Typed artifact get remains useful for manifest metadata. New generated Artifact IDs use `artifact_`; existing IDs remain unchanged. New PDRs are artifact/report, while historical document/pdr Records are also readable through universal get. Do not add a prefix to an existing ID. ```bash yy ledger artifact search --profile report --projection summary --limit 20 -f json yy ledger get RECORD_ID -f json # Explicit metadata-only native read: yy ledger artifact get RECORD_ID -f json yy ledger artifact history RECORD_ID -f ndjson ``` Use bounded metadata/summary projections before requesting payload details. For an unknown kind, discover with `yy ledger record search --projection summary --limit 20 -f json`. Exact get includes hot and archived Records in the selected project; discovery is hot-only unless `--scope archive|all` is explicit. Do not try other types or projects after an exact miss or ambiguity; preserve the diagnostic. Universal get includes readable UTF-8 local/inline content up to 64 KiB by default. Large/binary/non-UTF-8/external payloads return an omission reason, not empty successful content. With supporting help, use `yy ledger get RECORD_ID --content --max-content-bytes 1048576` for exact local/inline bytes; the maximum is 16 MiB. Select a fresh external output file and check exit status. This is not JSON output and `--raw` is not its substitute. Ledger never downloads external/link payloads; external retrieval requires separate authorization. Metadata/history readback is not byte round-trip proof. Verify profile, mode, media type, digest, size, provenance, retention, revision, immutable ID and the intended bytes before relying on evidence. Stop on corruption; do not silently use a different revision. Artifact payloads are immutable evidence. Represent replacement with explicit predecessor/successor relationships and the installed revision-safe update contract; do not overwrite bytes or edit content objects. Archive is a lifecycle transition, not deletion. Release, publication, external upload, retention execution, and production mutation always require separate authority. ## User-facing Record results After creation, update, discovery, or handoff, report the Record kind/profile, actual immutable Record ID, and actual Ledger slug from the returned Record or a native get readback. Never invent a slug from the title or confuse it with the ID. If the selected API omits a field, say it is unavailable rather than fabricate it. IDs remain authoritative for relations and lifecycle operations; slugs aid discovery. ## Complete request $ARGUMENTS