{"_id":"@aefree/pi-project-artifacts","_rev":"3-b936703f741f3ab723af19b41ccda6c5","name":"@aefree/pi-project-artifacts","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@aefree/pi-project-artifacts","version":"0.1.0","keywords":["pi-package"],"license":"MIT","_id":"@aefree/pi-project-artifacts@0.1.0","maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"homepage":"https://github.com/aefreedman/pi-project-artifacts#readme","bugs":{"url":"https://github.com/aefreedman/pi-project-artifacts/issues"},"pi":{"skills":["./skills"],"prompts":["./prompts"],"extensions":["./dist/pi/index.js"]},"dist":{"shasum":"3f759b40587bc1d4310a83ca45178a47577f4925","tarball":"https://registry.npmjs.org/@aefree/pi-project-artifacts/-/pi-project-artifacts-0.1.0.tgz","fileCount":47,"integrity":"sha512-LpAWN7llP17ILyUcND3iHvbovZ6+3MhBOlCWCc04gtWf14pUnFllqlZDRor/g80UVyjYSnucPajpsxH2IFdwCA==","signatures":[{"sig":"MEUCIQDqmF/vDRZOdFR+AgcIHbNZba63kTmp8Ok8BYRlYMLYhwIgHiyhCTy0DCDB4aaCqx/80ZYdAremGAOWbzyABnYpTEI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":281484},"type":"module","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./pi":{"types":"./dist/pi/index.d.ts","import":"./dist/pi/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js"},"./contracts":{"types":"./dist/contracts/index.d.ts","import":"./dist/contracts/index.js"},"./contracts/v1":{"types":"./dist/contracts/v1/index.d.ts","import":"./dist/contracts/v1/index.js"},"./contracts/v1/conformance":{"types":"./dist/contracts/v1/conformance.d.ts","import":"./dist/contracts/v1/conformance.js"}},"gitHead":"8692b1f11f372b75174244c312745d6c3be2faa7","scripts":{"test":"npm run build && node --test tests/*.test.mjs","build":"tsc -p tsconfig.json","pack:check":"npm pack --dry-run"},"_npmUser":{"name":"aefree","email":"aaron@secretcrush.net"},"repository":{"url":"git+ssh://git@github.com/aefreedman/pi-project-artifacts.git","type":"git"},"_npmVersion":"11.6.2","description":"Canonical project Markdown artifact search and atomic file-todo lifecycle tools with versioned provider contracts.","directories":{},"sideEffects":false,"_nodeVersion":"24.13.0","dependencies":{"@aefree/pi-capability-registry":"^0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"typebox":"1.3.8","typescript":"^5.8.3","@types/node":"^24.0.0","@earendil-works/pi-ai":"0.83.0","@earendil-works/pi-tui":"0.83.0","@earendil-works/pi-coding-agent":"0.83.0"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"typebox":{"optional":true},"@earendil-works/pi-ai":{"optional":true},"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/pi-project-artifacts_0.1.0_1785845882883_0.7495469959342258","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aefree/pi-project-artifacts","version":"0.1.1","keywords":["pi-package"],"license":"MIT","_id":"@aefree/pi-project-artifacts@0.1.1","maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"homepage":"https://github.com/aefreedman/pi-project-artifacts#readme","bugs":{"url":"https://github.com/aefreedman/pi-project-artifacts/issues"},"pi":{"skills":["./skills"],"prompts":["./prompts"],"extensions":["./dist/pi/index.js"]},"dist":{"shasum":"012c300933c5bba435f09b9a3a84b6a96af612b9","tarball":"https://registry.npmjs.org/@aefree/pi-project-artifacts/-/pi-project-artifacts-0.1.1.tgz","fileCount":47,"integrity":"sha512-cGW39RVq6h/m3KNKar9ihSZaUbhBNJFOiwNlf1OYDHaemLydCDYk65/BCIHQ0L9Z3YMqMJqbCAP6SaWnaYpY0g==","signatures":[{"sig":"MEYCIQDvYq451cvXTIWE18NdKejohdsWZjelNM2tuz+nU5TQQwIhAJXQN4WlhcCzZSOb6NFB+36KLiUHbHYJU9WixWn1izIW","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIG6b99cC41BfGRYcdmS9QJwMDHv2LAyp+1fMTMTMLamAAiBUHMspiiHtKmDwzlC/CuPipIbUKD+ZIRBQhJuEk93WAA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aefree%2fpi-project-artifacts@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":281449},"type":"module","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./pi":{"types":"./dist/pi/index.d.ts","import":"./dist/pi/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js"},"./contracts":{"types":"./dist/contracts/index.d.ts","import":"./dist/contracts/index.js"},"./contracts/v1":{"types":"./dist/contracts/v1/index.d.ts","import":"./dist/contracts/v1/index.js"},"./contracts/v1/conformance":{"types":"./dist/contracts/v1/conformance.d.ts","import":"./dist/contracts/v1/conformance.js"}},"gitHead":"808a2af485d513b343e1d04ec52c61bddd13058a","scripts":{"test":"npm run build && node --test tests/*.test.mjs","build":"tsc -p tsconfig.json","pack:check":"npm pack --dry-run"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:6e3a74a8-d204-45b0-b738-0b3e6b3cabad"}},"repository":{"url":"git+ssh://git@github.com/aefreedman/pi-project-artifacts.git","type":"git"},"_npmVersion":"11.6.2","description":"Canonical project Markdown artifact search and atomic file-todo lifecycle tools with versioned provider contracts.","directories":{},"sideEffects":false,"_nodeVersion":"24.20.0","dependencies":{"@aefree/pi-capability-registry":"^0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"typebox":"1.3.8","typescript":"^5.8.3","@types/node":"^24.0.0","@earendil-works/pi-ai":"0.86.1","@earendil-works/pi-tui":"0.86.1","@earendil-works/pi-coding-agent":"0.86.1"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"typebox":{"optional":true},"@earendil-works/pi-ai":{"optional":true},"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/pi-project-artifacts_0.1.1_1789916585777_0.34875563190701064","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"pi":{"skills":["./skills"],"prompts":["./prompts"],"extensions":["./dist/pi/index.js"]},"_id":"@aefree/pi-project-artifacts@0.1.2","bugs":{"url":"https://github.com/aefreedman/pi-project-artifacts/issues"},"dist":{"shasum":"11edb68afcbeb6b3870712f012773023ef08f289","tarball":"https://registry.npmjs.org/@aefree/pi-project-artifacts/-/pi-project-artifacts-0.1.2.tgz","fileCount":47,"integrity":"sha512-fziyRKuy+vtQ1RG0rkwBfBzoFRAo/ihfduqHVjnLKevpkCoKLRovXyw0SmPZ9WvvRUXh1BIaQgx3Z6MJQkajIA==","signatures":[{"sig":"MEUCIDKbjpB9L7Az3gftHgphehjt4KEJvKHg3ILWo9NHBKHgAiEA3hgiJjHCa96Bsvq1x0iLBH6iMeiwpLmH1Rb2dGVZKgs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGW1zqK/ZDxL52qhcaPjf+4v8NbW6ZKmm0N199mjHI+yAiABF7cSuZLFnqwYRoXxDxuHLDVciXiuBUhivSe9GWlZ6A=="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aefree%2fpi-project-artifacts@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":281558},"name":"@aefree/pi-project-artifacts","type":"module","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./pi":{"types":"./dist/pi/index.d.ts","import":"./dist/pi/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js"},"./contracts":{"types":"./dist/contracts/index.d.ts","import":"./dist/contracts/index.js"},"./contracts/v1":{"types":"./dist/contracts/v1/index.d.ts","import":"./dist/contracts/v1/index.js"},"./contracts/v1/conformance":{"types":"./dist/contracts/v1/conformance.d.ts","import":"./dist/contracts/v1/conformance.js"}},"gitHead":"81f61358166299a56a22ef8da0eb4268e97aef70","license":"MIT","scripts":{"test":"npm run build && node --test tests/*.test.mjs","build":"tsc -p tsconfig.json","pack:check":"npm pack --dry-run"},"version":"0.1.2","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:6e3a74a8-d204-45b0-b738-0b3e6b3cabad"}},"homepage":"https://github.com/aefreedman/pi-project-artifacts#readme","keywords":["pi-package"],"repository":{"url":"git+ssh://git@github.com/aefreedman/pi-project-artifacts.git","type":"git"},"_npmVersion":"11.6.2","description":"Canonical project Markdown artifact search and atomic file-todo lifecycle tools with versioned provider contracts.","directories":{},"maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"sideEffects":false,"_nodeVersion":"24.20.0","dependencies":{"@aefree/pi-capability-registry":"^0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"typebox":"1.3.8","typescript":"^5.8.3","@types/node":"^24.0.0","@earendil-works/pi-ai":"0.87.0","@earendil-works/pi-tui":"0.87.0","@earendil-works/pi-coding-agent":"0.87.0"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"typebox":{"optional":true},"@earendil-works/pi-ai":{"optional":true},"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-project-artifacts_0.1.2_1790020946238_0.7898386538335178"}}},"time":{"created":"2026-08-04T12:18:01.963Z","modified":"2026-09-21T20:02:26.661Z","0.1.0":"2026-08-04T12:18:03.180Z","0.1.1":"2026-09-20T15:03:05.860Z","0.1.2":"2026-09-21T20:02:26.339Z"},"bugs":{"url":"https://github.com/aefreedman/pi-project-artifacts/issues"},"license":"MIT","homepage":"https://github.com/aefreedman/pi-project-artifacts#readme","keywords":["pi-package"],"repository":{"url":"git+ssh://git@github.com/aefreedman/pi-project-artifacts.git","type":"git"},"description":"Canonical project Markdown artifact search and atomic file-todo lifecycle tools with versioned provider contracts.","maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"readme":"# @aefree/pi-project-artifacts\n\nCanonical project-local Markdown discovery and deterministic file-todo lifecycle infrastructure for Pi. Project Markdown remains authoritative; indexes and tool output accelerate discovery but do not replace source evidence.\n\n## Pi resources\n\n- tools: `project_artifact_describe`, `project_artifact_search`\n- tools: `project_todo_validate`, `project_todo_list`, `project_todo_inspect`, `project_todo_allocate`, `project_todo_create`, `project_todo_transition`\n- prompt: `/memorize`\n- skills: `using-project-artifacts`, `file-todos`, `grooming-project-artifacts`\n\nThe package registers `ArtifactSearchServiceV1` and `TodoLifecycleServiceV1` per Pi session. It owns the side-effect-free artifact profile/service contracts under `@aefree/pi-project-artifacts/contracts/v1`; providers such as `pi-unity` register through those contracts in either load order. See [Developing artifact-profile providers](docs/artifact-profile-providers.md) for the optional-peer, runtime-rendezvous, lifecycle, conformance, and schema-evolution contract.\n\n## Installation\n\n```bash\npi install npm:@aefree/pi-project-artifacts@0.1.0\n```\n\nUse `pi install -l npm:@aefree/pi-project-artifacts@0.1.0` for a project-local installation.\n\n`/memorize` persists one verified reusable learning as authoritative project Markdown in either the project's `solutions/` domain (verified technical problem/resolution) or `memories/` domain (verified durable non-solution knowledge). Invocation authorizes only one resolved artifact creation or focused update; evidence, duplicate detection, destination resolution, profile constraints, and post-write validation remain mandatory. It never routes output to another artifact class or claims model, session, or global user memory.\n\n`grooming-project-artifacts` owns the read-first procedure for organizing, normalizing, deduplicating, and optionally cleaning up project Markdown. It uses structured artifact search plus exact source evidence, leaves profile-defined migrations to owning migrators, and requires explicit authority before edits.\n\n## Artifact indexes\n\nAuthoritative data remains project Markdown under resolved docs/todos roots. Every artifact and todo invocation is privately bound to the session's physical `ctx.cwd`: the selected workspace and custom docs/todos roots must resolve to that directory or a physical descendant. Parent, sibling, home, and symlink/junction escapes fail before lock acquisition or artifact/todo reads and writes. Nested child repositories remain supported when a coordination workspace is the session cwd.\n\nDerived indexes use:\n\n```text\n<workspace>/.pi-project-artifacts/index-v1.json\n<workspace>/.pi-project-artifacts/index-v1-<label>-<hash>.json\n```\n\nThe v1 envelope identifies its schema, workspace/docs/todos physical roots, stable root identity, contributing profiles, content hashes, and complete entries. Strict refresh detects add/update/delete and external edits. Auto mode uses dirty tracking plus a bounded TTL; memory mode deliberately trusts the loaded index. Search details expose `cacheState` as `auto_fast_path`, `memory_fast_path`, `validated_unchanged`, or `rebuilt`, and the text summary names the corresponding behavior.\n\nThe index is disposable cache data rather than project documentation. Consumer projects should normally add only its generated directory to `.gitignore`:\n\n```gitignore\n.pi-project-artifacts/\n```\n\nDo not ignore authoritative `docs/` or `todos/` Markdown.\n\nPre-existing `.compound-game-dev/artifact-index*.json` files are never read by default, imported, moved, or deleted. An explicit occupied `indexPath` is replaced only when absent or when its entire recognized project-artifact envelope validates. Unrelated JSON, malformed envelopes, authoritative-root overlap, and physical symlink/junction escapes fail closed.\n\nIndex writes use process-local queues, schema-owned interprocess locks, exclusive temporary files, file sync, atomic replacement, orphan-temp cleanup, and structured stale/malformed-lock diagnostics. Locks carry random nonces; dead-owner reclamation and release first rename to a nonce-qualified quarantine and verify ownership before deletion.\n\n## Documentation discovery and profiles\n\nMarkdown files under the resolved project roots are authoritative. `docs/plans/`, `docs/solutions/`, and `docs/memories/` are recognized optional conventions, not required roots or a restriction on other documentation. Solutions hold verified technical problem/resolution learnings; memories hold verified durable project knowledge that is not a solution. The package never creates these directories or artifacts automatically.\n\n`project_artifact_search` indexes and exact-filters every supported top-level YAML-frontmatter key without requiring a known schema or an installed profile. It supports mixed and custom metadata schemas in one workspace. Use compact `project_artifact_describe` first: it lists every observed field name and document count without examples. `outputMode: \"detailed\"` adds type/cardinality evidence but still omits examples unless a non-empty, unique list of at most 20 exact `fieldNames` is supplied with `includeSamples: true`; compact mode always omits samples. Credential-like and absolute-path examples remain suppressed. Use `project_artifact_search` for parse/index/filter/rank/freshness candidate retrieval and bounded validation summaries. Then read the selected Markdown for final evidence.\n\n- The index stores only a body preview: body search/snippets are bounded candidate signals, not exhaustive full-body or exact-match evidence. Compact describe provides the complete observed top-level field-name/count inventory; examples are optional, bounded, and redacted. Use direct `rg` against source files for exhaustive or literal body search, then read the matching files.\n- YAML frontmatter is a schema-open fast path: use exact `filters` values for any supported top-level metadata field, including fields not described by a profile. General text search considers frontmatter values, not field-name labels; result text/details show only query/filter-relevant, character-bounded metadata facets (plus todo status/priority and bounded profile-warning evidence). Facet and warning summaries disclose their total, omitted, shortened, and truncation state; full metadata and validator payloads remain in the authoritative Markdown/index rather than search output.\n- Search results label exact raw metadata matches as `raw_exact`; a compatible profile may additionally label them `profile_validated` or `profile_warning`. These labels report confidence/diagnostics and never change whether the raw exact filter is permitted.\n- Profiles optionally enrich known fields with types, enums, applicability, and diagnostics. They never grant or withhold permission to discover or filter metadata, and no profile is required for generic or unknown-field search.\n- Arbitrary project Markdown and its metadata remain authoritative, readable source material; the index, definitions, availability, observations, and profile results are derived aids.\n\n## Atomic file todos\n\nCanonical identity:\n\n```text\n{positive-id-rendered-to-at-least-3-digits}-{pending|ready|complete}-{p1|p2|p3}-{kebab-description}.md\n```\n\nThe lifecycle service:\n\n- validates filename/frontmatter identity and diagnoses malformed files, duplicate numeric IDs, and normalized/case-fold collisions;\n- treats pre-existing conflicts as consumer-owned and blocks mutation without repair;\n- computes directory/content hashes for optimistic concurrency;\n- allocates again under a root lock and creates final targets exclusively;\n- stages create content and rolls back only writes whose hash still proves run ownership;\n- records transitions in durable per-run journals with source/target hashes, allowing a later locked mutation to deterministically resume a published destination or roll back a transition that never published one after process death;\n- serializes root allocation plus canonical per-file mutation queues; the Pi transition adapter also joins Pi's shared `withFileMutationQueue` for built-in edit/write coordination;\n- changes transition filename/frontmatter status together while preserving body and unknown frontmatter text;\n- validates both session-cwd containment and operation-root containment before I/O and never follows todo symlink aliases.\n\nAn allocation result is a preview, not a reservation. Use its `directoryHash` with `project_todo_create` when possible. Use a fresh `contentHash` with `project_todo_transition`.\n\n## Contracts\n\nPublic subpaths:\n\n- `@aefree/pi-project-artifacts/contracts/v1`\n- `@aefree/pi-project-artifacts/contracts/v1/conformance`\n- `@aefree/pi-project-artifacts/core`\n- `@aefree/pi-project-artifacts/pi`\n\nProvider/runtime callbacks receive fresh execution contexts and invocation-owned cancellation. Registry state is scoped by `ctx.sessionManager`, uses stale-safe registration tokens, and is resolved at execution time.\n\n## Independent packaging\n\n`@aefree/pi-capability-registry` is a semver dependency co-installed by the consumer. Decomposition packages are not recursively bundled, which prevents sibling workspace links or duplicate physical implementations from entering tarballs. Pi runtime packages remain optional peers.\n\n```bash\nnpm test\nnpm pack --dry-run\n```\n\nRepository-only behavioral eval seeds live under `evals/`; they cover artifact-skill activation, safe search routing, memorize behavior, and todo behavior. They are not included in the npm package, and live model trials are opt-in rather than part of `npm test`.\n","readmeFilename":"README.md"}