@tiangong-lca/pcr 0.4.0 → 0.4.2

package/README.md

@@ -9,13 +9,17 @@ Skill. Install the content separately with
 
 ## Install and run
 
-Requires **Node.js 24.19 or later**. Supported platforms are Linux x64, Windows
-x64, and macOS ARM64.
+Requires **Node.js 24.19 or later**. Supported platforms are Linux x64/ARM64,
+Windows x64, and macOS ARM64.
+
+These examples target PCR 0.4.2. Use the registry commands after guarded
+publication makes that version available; source metadata and a preparing release
+do not establish public availability.
 
 In a project directory:
 
 ```sh
-npm install @tiangong-lca/pcr@0.4.0 @tiangong-lca/pcr-library@0.4.0
+npm install @tiangong-lca/pcr@0.4.2 @tiangong-lca/pcr-library@0.4.2
 ./node_modules/.bin/tiangong-pcr library verify --format json
 ./node_modules/.bin/tiangong-pcr list --format json
 ```
@@ -32,6 +36,41 @@ The selection order is `--library`, then `PCR_LIBRARY`, then the installed
 content package. `--root` explicitly selects a source checkout and cannot be
 combined with `--library`.
 
+## Latest compatible content for a new task
+
+Released `@tiangong-lca/cli` 0.1.25 or later can manage content freshness separately
+from this offline reader; 0.1.25 is the qualified minimum for this workflow.
+Use Node 24.19.0 for this task workflow; Tiangong CLI supports `>=24.19.0 <25`,
+separately from the standalone PCR reader requirement above. After confirming its
+publication, install that qualified version:
+
+```sh
+npm install @tiangong-lca/cli@0.1.25
+```
+
+Select this installed PCR package's absolute root once when preparing a dedicated
+task directory:
+
+```sh
+./node_modules/.bin/tiangong-lca pcr snapshot ensure --task-dir <absolute-task-dir> --tool-root <absolute-installed-PCR-package> --json
+./node_modules/.bin/tiangong-lca pcr snapshot status --task-dir <absolute-task-dir> --json
+./node_modules/.bin/tiangong-lca pcr exec --task-dir <absolute-task-dir> -- list --format json
+```
+
+On Windows, use `node_modules/.bin/tiangong-lca.cmd` for this preparation CLI.
+
+Require `task_usable: true`. A new connected task selects the latest compatible
+published content, while an existing task retains its version/hash without
+network discovery. Explicit-version and offline modes remain available through
+command help. The wrapper injects the selected library/hash; do not pass native
+source overrides. It keeps the selected installed reader bytes fixed as well.
+This is an explicit workflow preparation boundary, not a hook into every chat or
+Foundry task. Standalone commands below preserve their existing behavior.
+Content compatibility is independent of its product version: a capable reader
+0.4.1 can consume newer content when its declared compatibility and any audited
+legacy reader profile permit it. Keep that reader and an existing task's content
+pin; a new website or release does not upgrade either implicitly.
+
 ## Common commands
 
 ```sh
@@ -72,15 +111,15 @@ package is optional; legacy `validate-model` only checks qualifier text and
 On a connected machine, download both packages:
 
 ```sh
-npm pack @tiangong-lca/pcr@0.4.0
-npm pack @tiangong-lca/pcr-library@0.4.0
+npm pack @tiangong-lca/pcr@0.4.2
+npm pack @tiangong-lca/pcr-library@0.4.2
 ```
 
 Transfer the two tarballs and a suitable Node.js runtime to the offline machine.
 In the destination directory:
 
 ```sh
-npm install --offline --ignore-scripts --no-audit --no-fund ./tiangong-lca-pcr-0.4.0.tgz ./tiangong-lca-pcr-library-0.4.0.tgz
+npm install --offline --ignore-scripts --no-audit --no-fund ./tiangong-lca-pcr-0.4.2.tgz ./tiangong-lca-pcr-library-0.4.2.tgz
 ./node_modules/.bin/tiangong-pcr library verify --format json
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiangong-lca/pcr",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "Offline PCR consumer CLI and agent Skill",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "README.md",
     "LICENSE",
     "NOTICE.md",
+    "reader-capabilities.json",
     "product-release.json"
   ],
   "dependencies": {
@@ -36,7 +37,7 @@
     "type": "git",
     "url": "git+https://github.com/tiangong-lca/pcr.git"
   },
-  "gitHead": "d0198577159e82bcc12df14bfe59f8ed060e089a",
+  "gitHead": "008da151ed2ddf3c880f75f92ee5847301393e44",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"

package/product-release.json

@@ -1,7 +1,7 @@
 {
   "schema": 1,
-  "version": "0.4.0",
-  "tag": "v0.4.0",
-  "sourceCommit": "d0198577159e82bcc12df14bfe59f8ed060e089a",
-  "sourceFingerprint": "sha256:79e28dac12e712c30cc77e1cb0a86f3ed63a06e10a1fb22602213456ef906090"
+  "version": "0.4.2",
+  "tag": "v0.4.2",
+  "sourceCommit": "008da151ed2ddf3c880f75f92ee5847301393e44",
+  "sourceFingerprint": "sha256:65e8a3449f7719b63e07b747fb52b6cb82282820ee623c099e15ccdd42692ff6"
 }

package/reader-capabilities.json

@@ -0,0 +1,12 @@
+{
+  "schema": 1,
+  "kind": "pcr-reader-capabilities",
+  "libraryFormats": [
+    1
+  ],
+  "projectionContracts": [
+    "1",
+    "2"
+  ],
+  "commandProtocol": 1
+}

package/skills/tiangong-pcr/SKILL.md

@@ -10,22 +10,64 @@ route from the user's task. General LCA authoring has no mandatory data-package
 format; native TIDAS inputs can be reviewed directly. The Agent interprets scope,
 applicability and evidence. The CLI supplies source-addressable facts and arithmetic.
 
-## Prepare the local tools
-
-`@tiangong-lca/pcr` bundles this Skill; copy its complete directory to the host's
-configured skills directory. npm installation does not activate it. Provision
-Node 24.19+ and the tool before going offline; do not fetch tools with npx.
-The separate `@tiangong-lca/pcr-library` supplies English-only methodology.
-
-Set `PCR_LIBRARY` to the absolute `library.sqlite` path, or use `--library` on PCR
-commands. Run `tiangong-pcr library verify --format json`, retaining the tool/content
-versions and snapshot hash. Keep the same immutable snapshot throughout the task;
-`--library-sha256 sha256:<hex>` adds strict byte pinning. `inspect` and `calculate`
-use local inputs without a library selector. Repository maintainers may use
-`npm --silent run tiangong-pcr -- ... --root <repo>`.
-
-The CLI never calls a model or retrieves missing datasets. Fully offline semantic
-work requires the host Agent/model to be available offline too.
+## Prepare and pin the PCR task
+
+Use released `@tiangong-lca/cli` 0.1.25 or later providing `pcr snapshot ensure`;
+0.1.25 is the qualified minimum for this preparation workflow. Use the qualified
+Node 24.19.0 runtime; Tiangong CLI supports `>=24.19.0 <25`. Select the installed
+`@tiangong-lca/pcr` reader independently. Content's
+declared compatibility, including the current 0.4.1 minimum reader, determines
+whether that reader can consume it; matching product versions are not required.
+Confirm the required versions are published before installing them; source or
+release-preparation metadata does not establish registry availability.
+Provision these tools before going offline. This Skill ships with the PCR reader;
+install its complete directory following the host's Skill setup. npm installation
+alone does not activate it, and it is not an automatic runtime hook. No account
+login is required for public PCR snapshots or local consumption.
+
+At the preparation boundary of a new PCR-guided task, use its dedicated absolute
+task directory. Reuse the supplied task directory when continuing work; never
+silently create a new directory merely to refresh an existing task. If there is
+no task directory yet, create one dedicated to this task and retain its path with
+the work artifacts. Do not use a shared project root as every task's identity.
+
+```sh
+tiangong-lca pcr snapshot ensure --task-dir <absolute-task-dir> --tool-root <absolute-installed-PCR-package> --json
+tiangong-lca pcr snapshot status --task-dir <absolute-task-dir> --json
+tiangong-lca pcr exec --task-dir <absolute-task-dir> -- guidance --pcr <id> --topic overview --format json
+```
+
+For a new connected task, ensure checks the latest compatible stable published
+snapshot, verifies it and records immutable data/tool pins. Continue only when
+`task_usable` is true. A prior task lock is reused without checking latest;
+repeated ensure may finish verification of the same partial preparation but
+cannot upgrade that task. Preserve the lock files with the task. Tool and
+content versions may differ when their explicit compatibility contract permits it.
+
+Honor an explicit version, selected local snapshot or offline request rather than
+using default online discovery. Use ensure's `--version`, or `--library` with an
+independently trusted `--library-sha256`; add `--offline` for verified cached
+selection without network. Read its help for supported legacy/local profiles.
+Offline selection is not proof of publisher latest. Missing compatibility,
+corrupted cache/tool bytes or failed native verification must be resolved before
+consumption; do not bypass the task lock by switching to an unpinned command.
+
+In the task-managed route, invoke the PCR arguments in the sections below through
+`tiangong-lca pcr exec --task-dir <absolute-task-dir> -- ...`. Follow-up/page
+commands returned by the standalone reader may include `--library` or
+`--library-sha256`; retain their query/page arguments but remove source selectors
+and route them through pcr exec, which injects the verified task pin. Do not
+forward `PCR_LIBRARY` or `--root` into this route. Native command help works after
+`--`. Inputs and output paths are relative to the task directory; use absolute
+paths when the work artifacts live elsewhere.
+
+An explicitly requested standalone or repository-maintainer workflow remains
+available: use `tiangong-pcr` with explicit snapshot/hash selectors, or the
+repository command with `--root`. Preserve the user's source choice and its
+identity; do not call it an automatically updated published-snapshot task.
+`inspect` and `calculate` use local inputs; the task wrapper still verifies its
+retained context. Neither CLI calls an LLM or approves methodology. Fully offline
+semantic work also requires the host Agent/model to be available offline.
 
 ## Select applicable methodology
 
@@ -52,7 +94,7 @@ for large results. Full `guidance` remains available for a saved complete view.
 
 For several known PCRs, save `{ "schema_version": 1, "pcr_ids": ["<id>"] }`
 and prefer `guidance batch --input <request.json> --output <new-result.json> --format json`
-with the same library selector. The fresh output file holds the complete result;
+through the same task wrapper (or the same explicit standalone library selector). The fresh output file holds the complete result;
 stdout is its receipt. Read the needed complete units and ancestor context from
 that file. At most 100 IDs share one verified session; order is preserved and a
 failed item rejects the whole batch.

package/skills/tiangong-pcr/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TianGong PCR"
+  short_description: "Use task-pinned PCR guidance for LCA and TIDAS work"
+  default_prompt: "Use $tiangong-pcr to prepare or resume a verified task snapshot and apply its complete methodology context to this LCA task."

package/skills/tiangong-pcr/references/cli-usage.md

@@ -1,7 +1,12 @@
 # PCR consumer commands
 
 Use command-specific `--help` for input shapes, defaults and next actions. Commands
-below run without network access; provision tool/library/optional TIDAS tooling first.
+below are native PCR arguments and run without network access; provision the reader first.
+For a managed task, prepare once with `tiangong-lca pcr snapshot ensure`, then invoke
+`tiangong-lca pcr exec --task-dir <absolute-task-dir> -- <arguments below without tiangong-pcr>`.
+Preparation may discover/download public data for a new task; existing task pins
+never refresh. Require `task_usable: true`, retain the same task directory, and
+use absolute input/output paths when files are outside that directory.
 
 ```sh
 tiangong-pcr tree --format markdown
@@ -22,12 +27,15 @@ tiangong-pcr review check --pcr <id> --input process.json --related ./datasets -
 tiangong-pcr feedback draft --pcr <id> --type <feedback-type> --summary "<finding>"
 ```
 
-Use returned page commands. Topic/section selection and exact pointer reading are
+Use returned page/query arguments. In the task-managed route, remove the returned
+standalone executable and any source selectors before passing arguments to
+`pcr exec`; the wrapper supplies the retained library/hash and rejects overrides. Topic/section selection and exact pointer reading are
 exclusive. New inspection/selection results use previews; truncated values carry
 an explicit marker and a pointer for complete retrieval. Large complete output
 requires `--output <new-file>`; existing files are not overwritten. This saves an
 artifact and prints its path/hash. Input inspection and arithmetic do not need
-`--library`; PCR commands honor PCR_LIBRARY or explicit selection/pinning.
+`--library`; standalone PCR commands honor PCR_LIBRARY or explicit selection/pinning.
+The managed wrapper instead verifies its task pins and clears ambient source overrides.
 
 `--related` scans one explicitly supplied local directory, bounded to 200 JSON
 files, 64 MiB total, 12 directory levels and 5000 entries. Each JSON file is bounded