docType: repo-readme scope: repo status: current authoritative: true owner: cli language: en whenToUse: "When installing, running, or validating the Tiangong AI CLI." whenToUpdate: "When package name, Node baseline, command examples, environment variables, or validation commands change." checkPaths:

• README.md
• package.json
• bin/**
• src/** lastReviewedAt: 2026-09-14 lastReviewedCommit: facc1b0aaac8a353ddae6773e68bcdb267d1a5ea

Tiangong AI CLI

Package: @tiangong-ai/cli Executable: tiangong-ai Node: >=24

Feedback

Use the Bug and feature forms and reporting guide. Chinese and English reports are welcome; unknown versions or incomplete reproduction are accepted with an explanation. CLI help exposes these links, and the npm package includes CONTRIBUTING.md. For Skill instructions and orchestration, use the Skills forms; uncertain ownership can be reported here for maintainer triage.

Run From This Repository

npm install
npm run build
node ./bin/tiangong-ai.js --help
node ./bin/tiangong-ai.js --version

Use Node 24.x; this package declares >=24 <25 and includes .nvmrc for compatible version managers.

After installation, print the package version with either top-level flag:

tiangong-ai --version
tiangong-ai -v

Atomic Data Runtime

Inspect the built-in, versioned data capability catalog without network access:

tiangong-ai data catalog --json
tiangong-ai data describe <capability-id> --json
tiangong-ai data doctor <capability-id> --json

Only explicit doctor --live and run operations may contact a provider. A run accepts one closed request envelope from a file or stdin:

tiangong-ai data run <capability-id> <operation-id> \
  --input /absolute/path/to/request.json --json

The command-line capability and operation must match the versions in the input envelope. Credentials are never accepted in argv or input JSON. Each connector declares exact logical environment-variable bindings, HTTPS endpoint scopes, and acquisition limits in its execution manifest. Callers may explicitly tighten those limits, but upper layers do not silently reinterpret Agent context budgets as provider or record limits. Data commands deliberately do not load a cwd .env file.

data catalog also returns a concise capability summary, what the capability provides and does not provide, operation summaries, a separate discovery digest, and an explicit available or suspended status. Suspended entries remain inspectable, but doctor and run block before any provider request. data describe expands that layer with source ownership, coverage, granularity, selection hints, typical uses, official documentation, freshness, license restrictions, and operation descriptions. Narrative discovery changes do not change the execution manifest digest used for compatibility binding. Operation input schemas include field-level descriptions and examples. Operations may also publish stable feature IDs for Skills that depend on a specific compatible behavior within the same contract major.

GDELT DOC requests are paced at least five seconds apart within one CLI process, including split queries and retries. Missing-header 429 responses use bounded exponential backoff and remain rate-limited, never no-results. Independent processes sharing an egress must be coordinated by the caller. The opt-in positive live gate and its timing/throughput definitions are documented in repository validation.

Auto Research keeps three budgets separate: connector acquisition limits, Evidence package bytes/files, and the Agent-visible context view. A validated result is persisted in full when it fits the Evidence package budget; maxBrokerItems and the context-token ceiling only shape the Agent view. Receipts distinguish provider coverage, explicit limits reached, and context projection instead of forcing them into one status. A projected result returns an opaque, evidence-bound cursor; research project evidence data read serves the next shape-aware view from immutable local Evidence without another provider request or provider quota charge. Agents must either continue until nextCursor is null or disclose the exact presented/total fraction. The public Research command returns receipt identity, coverage, a structured bounded context view, and continuation metadata. The complete core result remains in immutable Evidence and is not duplicated into Agent stdout.

JSON exits are 0 for success, 2 for request/contract errors, 3 for a blocked execution, and 4 for an explicit partial result. Public machine schemas ship under dist/data/schemas/.

The built-in capabilities are:

• airnow.hourly-observations / fetch-hourly: fetches official AirNow HourlyAQObs files for a bounded UTC-hour window, bounding box, and pollutant list. Results retain source-file lineage and always state that AirNow data are preliminary and unsuitable as regulatory-grade AQS evidence. Independent hourly files use bounded concurrency while output files and records retain deterministic UTC-hour order. Execution uses the official files.airnowtech.org S3 bucket through its regional S3 endpoint so a failing CloudFront edge does not make the underlying public object unavailable.
• bluesky.public-posts / fetch-cascades: fetches bounded public Bluesky post seeds from search, an author feed, a custom feed, or a list feed and can flatten visible reply cascades. Ranking, counters, moderation visibility, and missing nodes remain explicit mutable AppView limitations.
• epa.eis-records / search: retrieves bounded official EPA EIS Database common-search or UI-created search pages and parses title, CEQ/provider IDs, document type, dates, agencies, state, detail links, and document-availability cues. Its endpoint-scoped, same-origin session cookie jar exists only in memory so the provider's initial redirect can complete; cookies never enter results, receipts, logs, or cross-origin requests. It does not fetch or assess linked EIS documents.
• federal-register.documents / search: searches bounded FederalRegister.gov document metadata by publication date plus term, agency, document type, topic, docket, or RIN filters. It does not follow result links, fetch document full text, or provide legal interpretation.
• gdelt.doc-search / search: searches the rolling GDELT DOC 2.0 index for bounded article-link metadata or supported aggregate timelines. Automated multilingual extraction and uneven monitored-source coverage are explicit; it does not retrieve article bodies or establish ground-truth facts. The capability is currently suspended because representative modes do not pass a stable live gate under the provider's dynamic load shedding.
• gdelt.web-ngrams / search: searches literal 1–4-word phrases in one explicit published UTC minute's GZIP NGrams/TOC pair, returning matched article links with file-scoped IDs. This local candidate extension is a separately selected file-based alternative to DOC discovery, not a DOC query or timeline substitute. Missing files block; malformed rows and omitted matches are partial. No implicit time-range sampling or automatic fallback.
• gdelt.events, gdelt.gkg, and gdelt.mentions / fetch: independently discoverable GDELT 2.0 table capabilities backed by one bounded TypeScript file-feed core. They fetch either the latest provider entry or at most twenty aligned 15-minute files, verify ZIP/CRC and advertised latest-file checksums, and emit closed named columns without persisting downloaded files. Their wide named-field JSON is preserved as Evidence; Agent context projection is handled by Auto Research without changing the connector result.
• nasa-firms.active-fire / fetch-area: retrieves bounded NASA FIRMS MODIS, VIIRS, or Landsat active-fire point detections, optionally validates source availability, and exposes chunk-level partial coverage. Hotspots are thermal anomalies, not fire perimeters or confirmed incident identities.
• open-meteo.air-quality / fetch-hourly: retrieves bounded GMT hourly CAMS model-grid air-quality series for known coordinates; these are modeled background values rather than station observations. Missing and explicitly returned all-null series are distinct machine-readable partial issues.
• open-meteo.flood / fetch-daily: retrieves bounded daily GloFAS simulated river-discharge series for the represented river grid; it is neither gauge data nor a flood-alert service. Missing and explicitly returned all-null series are distinct machine-readable partial issues.
• open-meteo.historical-weather / fetch: retrieves bounded GMT hourly and/or daily historical weather reanalysis for one controlled model and known coordinates. ERA5 or ERA5-Land should be selected when multi-decade model consistency matters. Missing requested series and provider-returned series whose values are all null are distinct machine-readable partial issues.
• openaq.air-quality / search-locations and fetch-sensor-measurements: discovers filtered OpenAQ v3 locations and retrieves a bounded raw, hourly, or daily series for one sensor. It preserves provider/license context but does not calculate AQI or make health or regulatory determinations.
• usbr.project-records / fetch: inventories caller-supplied official www.usbr.gov project or program pages plus bounded same-origin links. It preserves page response provenance but does not follow, download, parse, or assess linked records and is not USBR-wide search. Execution is currently suspended because the official origin returns a gateway rejection page in the supported CLI environment.
• usbr.rise / discover-items and fetch-results: scans bounded Bureau of Reclamation RISE catalog pages for client-filtered candidate item IDs, then retrieves bounded result rows for explicitly selected items. Provider scan order is not ranking, and operational values require item metadata and domain context before interpretation. Execution is currently suspended because both the legacy API and the official EDR beta endpoint are rejected by the provider gateway in the supported CLI environment.
• usgs.water-instantaneous-values / fetch: retrieves bounded legacy USGS WaterServices instantaneous observations while preserving site, parameter, qualifier, provisional status, and source lifecycle warnings.
• youtube.public-content / search-videos and fetch-comments: discovers public YouTube videos with detail enrichment and fetches bounded visible comment/reply text for explicit video IDs. It does not download media or transcripts and does not treat ranking or comments as representative opinion.

GDELT DOC, Regulations.gov comment/attachment, USBR RISE, and USBR project records remain discoverable with availability.status=suspended, a stable reason code, and explicit resume criteria. doctor and run block locally without network access, and Auto Research excludes them from its executable projection until their production live gates qualify them again.

Of the fifteen execution-enabled capabilities, twelve are keyless. NASA FIRMS requires NASA_FIRMS_MAP_KEY, which the CLI injects as a protected provider path segment; OpenAQ requires OPENAQ_API_KEY, and YouTube requires YOUTUBE_API_KEY; the CLI injects the latter two as protected provider headers, with YouTube using X-Goog-Api-Key rather than a URL parameter. No secret is accepted in argv or input JSON. Exact input and output schemas, endpoint scopes and limits are available through the execution manifest, while source notes, coverage, selection guidance and license restrictions are available in the discovery metadata returned by data describe; static data doctor remains offline and reports a missing required credential without making a network request.

Operations that declare local artifact output must be invoked with data run ... --artifact-dir <absolute-existing-directory>. The path is an out-of-band execution parameter and is excluded from the request, result, and receipt. Files are staged under hidden temporary names, validated before an atomic no-overwrite commit, and rolled back when execution or output validation is blocked.

KB Ingest

Required environment:

TIANGONG_AI_API_KEY=
TIANGONG_KB_DEFAULT_COLLECTION_NAME=

The KB API server defaults to https://thuenv.tiangong.world:7300 with path prefix /api/v1/kb.

Run a resumable sliding-window ingest for one file or a folder:

tiangong-ai kb ingest bulk /path/to/document.pdf \
  --collection-path /course/thu_humanities \
  --poll-interval 30 \
  --health-poll-interval 60

Run a larger folder ingest:

tiangong-ai kb ingest bulk /path/to/folder \
  --collection-path /course/thu_humanities \
  --window-size 100 \
  --top-up-max 50 \
  --upload-concurrency 4 \
  --poll-interval 30 \
  --health-poll-interval 60

Bulk scan a large folder and emit a structural JSON summary:

tiangong-ai kb ingest bulk scan /path/to/folder --json

Dry-run a layered metadata map against a folder and collection schema:

tiangong-ai kb ingest bulk dry-run /path/to/folder \
  --collection-path /course/thu_humanities \
  --metadata-map metadata-map.yaml \
  --json

The same dry-run is also available through the skill-facing alias:

tiangong-ai kb ingest metadata dry-run /path/to/folder \
  --collection-path /course/thu_humanities \
  --metadata-map metadata-map.yaml \
  --json

Run a resumable sliding-window bulk ingest with metadata:

tiangong-ai kb ingest bulk /path/to/folder \
  --collection-path /course/thu_humanities \
  --metadata-map metadata-map.yaml \
  --window-size 100 \
  --top-up-max 50 \
  --upload-concurrency 4 \
  --poll-interval 30 \
  --health-poll-interval 60

tiangong-ai kb ingest bulk run /path/to/folder is accepted as an explicit alias for wrappers that want a verb before the folder path.

Bulk ingest uses SQLite as its checkpoint source. By default, job files are stored under the OS app-data directory:

• macOS: ~/Library/Application Support/tiangong-ai/kb-ingest/jobs/<job-id>.sqlite
• Linux: ~/.local/share/tiangong-ai/kb-ingest/jobs/<job-id>.sqlite
• Windows: %APPDATA%/tiangong-ai/kb-ingest/jobs/<job-id>.sqlite

Use --state /path/to/job.sqlite to override the checkpoint path. Bulk ingest does not impose a client-side polling limit by default, so it can keep topping up the sliding upload window until all rows complete. Use --max-polls <n> only when a wrapper or operator needs a bounded run. Status checks and upload-window top-up run every 30 seconds by default. Pipeline health is cached independently and refreshed every 60 seconds by default, so health backpressure does not slow status progress. Override the intervals with --poll-interval and --health-poll-interval, or with TIANGONG_KB_BULK_POLL_INTERVAL and TIANGONG_KB_PIPELINE_HEALTH_POLL_INTERVAL.

Bulk ingest scans and fingerprints files first, then lazily creates derived files only when a row enters the active upload window. .docx files larger than 10MiB are uploaded through 300dpi-normalized ingest copies; smaller .docx files upload directly unless they are empty. Oversized PDFs are split into the fewest uploadable PDF parts when they enter the window, and the generated part rows are written back to SQLite so resume can reuse them. Derived files stay under .tiangong-kb-ingest-derived by default, and that directory is excluded from future bulk scans. Upload metadata remains the user/business metadata produced by the metadata map.

Manage bulk jobs:

tiangong-ai kb ingest jobs
tiangong-ai kb ingest status <job-id>
tiangong-ai kb ingest resume <job-id>
tiangong-ai kb ingest export <job-id> --format csv

List uploadable collections:

tiangong-ai kb collections list --capability upload

Resolve a collection and include the effective metadata schema:

tiangong-ai kb collections schema --collection-path /course/thu_humanities --json

Check document status:

tiangong-ai kb ingest status <document-id>

Read course fulltext from the processed S3 bucket:

tiangong-ai kb course fulltext \
  --document-id 000125ed-c4d9-4fe3-9380-000000000000 \
  --tags thu_humanities

The command lists exactly one .txt object under s3://tiangong/processed_docs/course_pickle/<tags>_pickle/<document-id>/ and prints its content. Override the location with --bucket, --prefix, or the TIANGONG_COURSE_FULLTEXT_S3_BUCKET and TIANGONG_COURSE_FULLTEXT_S3_PREFIX environment variables. AWS credentials and region are resolved by the AWS SDK, including AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_PROFILE, AWS_REGION, and AWS_DEFAULT_REGION.

Research Workspaces

Create a bounded smoke-test workspace and register a question:

tiangong-ai research workspace init /absolute/path/to/workspace
tiangong-ai research project init gpu-resource-impact \
  --workspace /absolute/path/to/workspace \
  --question "How do advanced GPU process nodes change environmental resource burdens?"

smoke-test is the default and is intended for deterministic fixtures and low-cost canaries. Formal work must use --mode production-research, explicit producer/reviewer model IDs and pricing in config.json, a requirements JSON file, and budget confirmation when maxCostUsd exceeds confirmationCostUsd:

tiangong-ai research setup catalog \
  --workspace /absolute/path/to/workspace --json
# Interactive and user-initiated: select external Skills, configure credentials
# with hidden input/env/stdin, review licenses, choose scope, and run checks.
tiangong-ai research setup \
  --workspace /absolute/path/to/workspace
tiangong-ai research setup status \
  --workspace /absolute/path/to/workspace --json
tiangong-ai research project preflight \
  --workspace /absolute/path/to/workspace \
  --question "How do advanced GPU process nodes change environmental resource burdens?" \
  --requirements /absolute/path/to/evidence-requirements.json --json
tiangong-ai research project init gpu-resource-impact \
  --workspace /absolute/path/to/workspace \
  --question "How do advanced GPU process nodes change environmental resource burdens?" \
  --requirements /absolute/path/to/evidence-requirements.json \
  --confirm-budget --json

The guided setup creates an immutable, hash-bound plan before mutation. No Skill is bundled or installed without an explicit Wizard confirmation or plan selection. The Wizard recommends a project-local tiangong-auto-research orchestrator so ordinary research requests can enter the workflow from any user-selected workspace directory. It pins the installer integrity, source commits, Skill tree hashes, exact destinations, license acceptance, safe credential bindings, settings, and checks. For every selected provider, the Wizard offers hidden TTY input (recommended), a named owner environment variable, preloaded bounded stdin/password-manager input, or an explicit skip. Secret values never enter the plan or terminal output. Required credential preflight and owner-only storage run before downloads. Project-local copy is the default; global writes, network downloads, live provider checks, synthetic document uploads, and paid agent smokes each require their applicable confirmation.

When the orchestrator is selected with project scope, the reviewed plan also binds its host-routing instructions. Codex receives one bounded managed block in the workspace-root AGENTS.md; setup preserves every owner byte outside that block. Claude Code receives the dedicated .claude/rules/tiangong-auto-research.md file and setup never replaces an owner CLAUDE.md. Existing conflicting, modified, linked, or otherwise unsafe targets stop apply before mutation. Replacement plans remove only routing bytes still proven to be setup-owned. Status and Doctor verify the installed bytes and report that a new native-host session is required before the routing instruction becomes active. Global-scope Skill installation does not create project instruction files.

Reviewed setup upgrades

Use research setup update --check --candidate-version <exact-stable-version> to inspect one explicitly selected release. Omitting --candidate-version keeps this a local catalog comparison with no registry request. The optional query pins the public npm registry and package scope, has finite time/output limits, and reports newer, same, older, or unavailable. Metadata includes the exact version, tarball URL, SHA-512 integrity and Git commit. This validates registry metadata; it does not independently download or authenticate the package. An unavailable query never means that no update exists: when there is no separately confirmed local migration, updateAvailable is null.

An older workspace resolver deliberately continues selecting its recorded CLI. To use an upgrade-capable candidate, select its exact published version and run that version directly; do not edit the runtime lock or use floating latest:

REVIEWED_UPGRADE_CLI_VERSION=X.Y.Z # replace with one reviewed exact stable release
npx --yes --registry=https://registry.npmjs.org \
  --@tiangong-ai:registry=https://registry.npmjs.org --strict-ssl=true \
  --package "@tiangong-ai/cli@$REVIEWED_UPGRADE_CLI_VERSION" -- tiangong-ai \
  research setup upgrade --plan --confirm-upgrade \
  --workspace /absolute/path/to/workspace --json

Review the returned immutable planPath and execute its applyCommand. The candidate also binds the SHA-256 identity of package.json, bin/ and dist/; apply and rollback reject changed CLI runtime bytes before workspace mutation. This content binding excludes installed dependencies and is not a publisher signature. Ordinary research commands do not rescan these trees. Planning leaves the active plan, runtime lock, configuration and installed Skills intact. Apply stages the complete selected generation, verifies each prior-owned tree, and reuses unchanged trees and verified downloads. Modified or linked targets remain protected. It preserves the workspace identity, evidence, credentials, budgets, current model/pricing choices, custom launchers and reviewer transport. Changed license choices remain explicit; unchanged accepted licenses carry forward.

An interrupted commit blocks ordinary workspace use and reports the exact candidate recovery command. Repeat that candidate's apply to resume, or use its rollbackCommand to restore the directly bound prior generation with the new updater. Rollback refuses conflicting owner changes or subsequent research activity. Interrupted rollback remains blocked and resumes with the same command. Private rollback preimages (including configured credentials) and prepared caches are retained for recovery; they are excluded from portable setup audit exports. Doctor runs after coherent activation; a repeated apply does not repeat a paid check that already started. If its result was lost, explicitly inspect status and run Doctor as needed. Old readiness attestations never certify new bytes. A legacy already-mixed plan/lock fails with RESEARCH_SETUP_LEGACY_UPGRADE_RECOVERY_REQUIRED; preserve its directly linked setup history for diagnosis rather than deleting Skills or rewriting locks.

Declarative setup

For repeatable provisioning without a TTY, generate a safe workspace-local template:

tiangong-ai research setup init \
  --workspace /absolute/path/to/workspace --json

This no-overwrite command creates:

• .tiangong-research/setup.yaml: every current catalog Skill, credential, and setting with explicit enabled/disabled state, plus license acceptances, agent routes, verification choices, and confirmations;
• .tiangong-research/setup.env.example: every catalog credential variable name with an empty value and matching requirement/enabled comments; copy it to setup.env only when a file-based secret source is needed;
• .tiangong-research/.gitignore: excludes setup.env.

Review the catalog, edit setup.yaml, and never put a key or token in it. For a file-based credential source:

cp .tiangong-research/setup.env.example .tiangong-research/setup.env
chmod 600 .tiangong-research/setup.env
# Edit setup.env locally. Keep disabled optional entries empty unless their
# corresponding credentials.<id>.enabled flag is explicitly changed to true.

Then run the ordinary command:

tiangong-ai research setup \
  --workspace /absolute/path/to/workspace --json

Bare setup checks only the fixed workspace-local setup.yaml; it never scans a parent directory. When the file exists, setup is fully non-interactive and does not fall back to the Wizard after a parse, schema, permission, credential, or readiness failure. Use absolute --config and --env-file paths only for an explicit alternative. Use research setup wizard to explicitly choose the interactive path even when a declaration exists.

The closed YAML declaration is schemaVersion: 2; the removed v1 shape is not migrated or accepted. It requires selection.skills, credentials, and settings to contain exactly all current catalog entries. Skill entries expose enabled and the catalog license ID. Credential and setting entries expose the catalog- and current-selection-derived requirement, catalog appliesTo, and an explicit enabled choice; optional omission is not a configuration state. Missing, extra, or drifted catalog metadata, incomplete Brave profile combinations, a disabled required entry, or an enabled setting without a value fails before network access.

setup.env must be a regular non-symlink file, no larger than 64 KiB, owner-only on POSIX, and may contain only credential variable names declared by the YAML. Empty values keep disabled options visible without selecting them. A non-empty value for a disabled credential is rejected; enable it in YAML or remove the value. The file is read as literal data without shell expansion. A differing value in the ambient environment and setup.env is also an error; setup never chooses between them silently. Enabled secret values are imported into the existing owner-only logical stores before downloads and never enter the YAML, immutable plan, declaration binding, output, report, or journal.

The semantic YAML hash is bound to the immutable plan. Re-running unchanged configuration reuses that exact plan and reruns all verification. A changed declaration stops until the owner reviews it and sets replaceExistingPlan: true; the prior plan and declaration binding are archived before replacement.

Declarative setup requires live provider checks and the independent reviewer CLI agent smoke, including explicit cost authorization. Interactive setup recommends both by default while retaining explicit quota/cost consent. Apply, status, doctor, and the Wizard return success only when overallReadiness=READY; skipped checks, warnings, missing dependencies, and optional selected-component failures remain visible as a non-zero incomplete setup instead of a false success. The native producer is still not launched as a child process.

Before project initialization, a setup-only audit can be exported without rerunning Doctor, contacting a provider, or launching a model. The exporter creates a new portable directory atomically and verifies it before returning. The independent verifier accepts the directory from any absolute location:

tiangong-ai research setup audit export \
  --workspace /absolute/path/to/workspace \
  --output /absolute/path/to/new-setup-audit --json
tiangong-ai research setup audit verify \
  --bundle /absolute/path/to/new-setup-audit \
  --expected-manifest-sha256 <digest-from-trusted-export-record> --json

The closed manifest binds portable projections of the immutable setup plan and state plus every available setup report, runtime/capability lock, Doctor attestation, and declaration binding. It rejects missing, extra, symlinked, reordered, hash-drifted, or semantically disconnected entries. Credential values and environment-variable names, owner secret stores, source caches, installed Skill trees, browser/auth state, raw provider output, unrelated workspace files, and host paths are never included. This setup proof is separate from research project audit: readiness may honestly be BLOCKED or PARTIALLY_READY while bundle integrity still verifies. Local capability locators, static-header values, credential prefixes, and free-form Doctor runtime/telemetry strings are represented only by SHA-256 bindings in their closed portable projections. Verification parses and checks the exact bytes captured with each file hash, then rejects a tree or file that changes before completion. The manifest digest returned by export is an external trust anchor: retain it in a separate run record, CI record, or other trusted channel. Verification requires that explicit digest and never trusts a digest read only from the mutable bundle itself.

If the full orchestrator was selected, accepted apply creates a separate project-local tiangong-auto-research-recovery Skill after credentials are stored and before source checkout. This CLI-generated, plan-bound shim can only inspect context/status and execute the exact-version retry returned by setup; it cannot perform research, call standalone evidence, or access credentials. A checkout or install failure therefore remains discoverable without falling back to a global Skill. After the full external orchestrator matches its reviewed tree hash, setup verifies the shim byte-for-byte and removes only that generated directory. Modified, symlinked, or ambiguous recovery bytes block cleanup.

Production admission requires at least one locked external capability with brokered-network and discoveryScopes: ["public-internet"]; an input plan or local files alone cannot represent internet coverage. The machine-readable setup catalog contains only separately sourced external Skills and reports each orchestrator, evidence, preprocessing, acquisition, and post-closure recommendation; exact source commit and tree hash; license and credential requirements; dependencies; and installed-byte status. Installation is never performed by a research package.

Whole-tree hashes are platform-stable: logical paths are NFC-normalized and ordered by UTF-8 bytes rather than the host locale, and newly created detached source checkouts disable Git line-ending conversion before checkout. A source hash mismatch remains fail-closed before npx skills add; its structured error reports only the Skill/source IDs, hash algorithm, and expected/observed hashes. Setup runs every nested npm installer through one apply-scoped owner-only cache under the OS temporary directory, never through the caller's HOME or global npm cache, and removes it after either success or failure. This keeps nested executables usable when HOME is mounted noexec without admitting mutable host cache state into a reviewed installation. It never treats file existence as installation success or silently rewrites an immutable plan. Plans created by an earlier CLI release are rejected at the execution boundary; create and review a new plan with the active release. The orchestrator additionally declares a workspace-lock runtime contract: every workspace command goes through its bundled resolver, which accepts only the regular non-symlink runtime-lock.json exact stable CLI version. Setup and release CI reject a missing resolver or any stale exact CLI version in the orchestrator's SKILL.md or references/*.md.

Top-journal Policy, scientific design, and publication gates

A top-journal project starts with a human-reviewed Markdown Policy, not with model execution. After project-scoped setup reaches READY, use the guided Wizard:

tiangong-ai research policy wizard top-journal-paper \
  --workspace /absolute/path/to/workspace
tiangong-ai research policy status top-journal-paper \
  --workspace /absolute/path/to/workspace --json

The Wizard resolves only the verified project-installed tiangong-auto-research tree. Before catalog use, the CLI parses every Markdown template in every category of that exact locked tree; setup doctor performs the same compatibility check before any provider live check or reviewer smoke. The baseline must require the scientific-design contract, ordered early reviews, and real-record construct canary, and those safeguards must remain true in the resolved Policy. The Wizard then copies a baseline plus one article type, field, journal class, project brief, and four reviewer rubrics. Generic defaults are clearly reported and require a separate acknowledgement. An exact-journal Policy additionally requires a current official HTTPS guideline URL, retrieval date, and substantive human content for all journal-specific sections. Approval binds the manifest and every document by SHA-256; edits, manifest tampering, or expiry block preflight and all later stages until the Policy is reviewed and approved again.

Before search, the current native Codex, Claude, WorkBuddy, or CodeBuddy host must author a project-specific scientific design. The CLI owns the closed schema and rejects designs that confuse model-to-model disagreement with observed truth, inflate independent sample size through resampling, omit quantity/threshold semantics, leave blocking gaps unresolved, or cannot fit the complete review lifecycle. The CLI validates, freezes, hashes, and routes this design; it does not author the design or launch a nested producer.

Hash binding alone does not make a model executable. Each model declares raw implementation bytes, a retrievable safe locator and entrypoint, exact environment-lock bytes, implementation/environment status, and a freeze gate. Before authoring a design with frozen model objects, register each external regular non-symlink file through the public content-addressed intake:

tiangong-ai research scientific object register \
  --kind model-implementation \
  --path /absolute/path/to/model.py \
  --media-type text/x-python \
  --workspace /absolute/path/to/workspace --json
tiangong-ai research scientific object register \
  --kind environment-lock \
  --path /absolute/path/to/requirements.lock \
  --media-type text/plain \
  --workspace /absolute/path/to/workspace --json

Use the returned sha256 and objectLocator verbatim in the design. Registration is workspace-scoped because it must happen before project admission. It hashes raw bytes, atomically stores an immutable lineage/objects/<sha256>/blob, and records only deterministic non-path metadata. It never accepts a source inside .tiangong-research, a symlink as the selected file, an unsupported/binary media type, or invalid UTF-8. Canonical parent-directory aliases are resolved before containment checks, including macOS /var aliases and Windows cross-volume paths. Re-registration is idempotent, and research scientific object inspect revalidates the record and blob before returning it. Do not hand-copy files into the control directory.

Source-derived uncertainty states also declare whether their values are frozen or pending, and every joint state maps exact parameter-state IDs. Pending model, environment, or uncertainty objects are allowed only when a planned Policy rule owns the same due gate. Pending implementations use null for implementation SHA-256, locator, and entrypoint; pending environments use null for lock SHA-256 and locator. They are exposed in every earlier review packet as futureGateObligations and become blocking mechanical errors at that gate. Their predeclared slots may be fulfilled through the append-only same-project command below. The original design bytes never change; a material assumption, question, policy or already-frozen value still requires a reviewed successor.

Use the same Policy project ID and exact design when preflighting and admitting the research project:

tiangong-ai research schema show scientific-design --json
tiangong-ai research project preflight \
  --question "A specific, testable research question" \
  --goal top-journal --policy-project top-journal-paper \
  --requirements /absolute/path/to/evidence-requirements.json \
  --design /absolute/path/to/scientific-design.json \
  --workspace /absolute/path/to/workspace --json
tiangong-ai research project init top-journal-paper \
  --question "A specific, testable research question" \
  --goal top-journal \
  --requirements /absolute/path/to/evidence-requirements.json \
  --design /absolute/path/to/scientific-design.json \
  --design-producer-agent codex \
  --design-producer-session OPAQUE_NATIVE_SESSION \
  --confirm-budget \
  --workspace /absolute/path/to/workspace --json

The base evidence lifecycle remains producer-authored in the current interactive Codex or Claude Code host, but its frozen control sequence is now discover -> acquire -> typed decomposition/atoms -> content freeze -> inference freeze -> analyze -> Claim-Evidence Graph -> synthesize -> review -> close. A fresh independent reviewer must first pass three hash-bound scientific gates: research-design before discovery, a real-record and outcome-blind evidence-construct canary after acquisition and typed-content freeze, and pilot-methods after that canary and before analysis. Acquisition always freezes its exact result, including honest gaps; a stopped acquisition/content gate prevents inference without discarding the acquired evidence. Evidence-construct coverage may cite only frozen snapshot source IDs and exact content atoms. Its JSON canary artifacts are promoted and content-addressed through --canary-artifacts; reviewer prose cannot override an invented ID, unbound digest, or other mechanical failure.

tiangong-ai research schema show scientific-assessment-research-design --json
tiangong-ai research project scientific review prepare top-journal-paper \
  --role research-design \
  --assessment /absolute/path/to/research-design-assessment.json \
  --reviewer-agent claude \
  --reviewer-session FRESH_OPAQUE_REVIEW_SESSION \
  --workspace /absolute/path/to/workspace --json
tiangong-ai research schema show scientific-review-research-design --json
tiangong-ai research project scientific review submit top-journal-paper \
  --role research-design --review /absolute/path/to/review.json \
  --workspace /absolute/path/to/workspace --json

For a prepared packet, use explicit isolated execution instead of writing a custom reviewer runner:

tiangong-ai research reviewer status --workspace /absolute/path/to/workspace --json
tiangong-ai research project scientific review execute top-journal-paper \
  --role research-design --confirm-review-cost \
  --workspace /absolute/path/to/workspace --json

Confirm the bounded cost before execution. The command uses the configured native-direct or sandbox-bridge reviewer, copies exact hash-verified packet inputs and human Policy documents into its capsule, and submits only a schema-valid, packet/session-bound review. A saved successful execution is replayed without another model call after revalidating its immutable proof. Failures require explicit --retry and remain bounded by the attempt budget; unreported usage and interrupted wall time retain conservative reservations. Failed processes return a bounded, sanitized exit diagnostic and record it in the journal; no full prompt or raw authentication output is persisted. When the reviewer returns but submission is rejected, the error and failed journal event also return an executionRecord locator and SHA-256. The locator is relative to .tiangong-research/ and points to an immutable scientific/failed-executions/ record containing the packet/run binding, reported usage and identity, rejection code, and safely retained JSON stdout. These are unaccepted execution observations, not a review receipt or permission to pass a gate. Inspecting them does not call the provider; another execution still requires explicit --retry. Retained stdout is limited to the smaller of 1 MiB and the configured output capture allowance. Unsafe, oversized, or malformed JSON keeps only its digest, size and omission reason. If storage fails, outputRetention=storage-unavailable is reported with the original error instead of claiming that a result was saved. Successful review and replay use their existing output/receipt without this additional failure capture. Automatic Claude invocation uses the same dialect-annotation conversion as research schema show NAME --compatibility claude-code; canonical controller validation and its scientific constraints remain unchanged. The provider view explicitly types scalar constants/enums; returned values are never coerced to satisfy the canonical schema. Claude's structured result is used instead of any accompanying narrative; declared error results remain failures, with their safe diagnostic ahead of incidental stderr warnings. A nonpassing mechanical packet can receive an independent stop verdict, never an override. The existing manual submit command remains available for an exact independent review.

Reviewer status is read-only and transport-aware. Native-direct does not require a bridge connection. Smoke configuration readiness is explicitly not production readiness and does not demand an attestation that smoke mode never writes. Production still requires its current reviewer doctor attestation. Packet read responses carry their actual content and receipt together; a receipt alone does not establish that the host displayed the content to its model.

Repeat the same prepare/execute route for evidence-construct, adding an owner-reviewed JSON array of absolute canonical canary paths with --canary-artifacts /absolute/path/to/canary-paths.json, and then for pilot-methods at its stage boundary. A top-journal fork or addendum is a new authoritative generation and therefore requires a target-specific approved Policy, design, and fresh native producer session; it cannot inherit scientific approval from a superseded generation.

Review packet stageInputs identify promoted portable objects by purpose, owner, safe source locator, media type, object kind, registration-record hash, and SHA-256 over raw file bytes. Registered model code and environment locks are copied as exact project-local blob bytes; they are never parsed as JSON merely because the packet is JSON. packetSha256 is the logical packet identity that excludes its own identity field; the portable audit manifest separately records the raw stored packet-file digest. This keeps packet identity and byte-level transfer verification explicit rather than overloading one hash with both meanings.

After base closure, inspect research publication lineage PROJECT --json before authoring materials. It verifies the existing closure and reviewed packet's analysis, report and evidence-chain hashes and returns their analysis identity with an empty material-file template. It does not certify or relabel previously authored files. The current native host then writes a final Markdown/plain-text manuscript, schema-valid publication assessment, and an explicit submission manifest. The manuscript must contain Abstract, Introduction, Methods, Results, Discussion, Data availability, Code availability, and References. Decimal section prefixes such as 1. Introduction, 2 Methods, 3.1 Results, and 4) Discussion are accepted when separated from the title by whitespace; unrelated titles and body text still cannot satisfy a required section. The submission manifest must bind distinct absolute files for cover letter, title page, reporting checklist, data availability, code availability, and source data; figure/table index, extended data, and supplementary methods are optional. The schema-version-1 submission manifest also requires resultLineage, following research schema show publication-result-lineage --json. Preserve the source analysis identity from material preparation. Include a role, actual byte SHA-256 and source analysisSha256 for the manuscript, assessment, every submission file and each supplement-N (one-based supplied order). Include the actual figures, tables and source inputs as submission files or supplements; an index alone is not their contents. Do not replace a stale parent hash merely to pass validation. Completeness and scientific derivation remain producer claims for independent review; the CLI verifies declared lineage and bytes, not scientific truth. research publication freeze then content-addresses the Policy, scientific design and early reviews, acquisition/content/inference snapshots, mode-bound analysis, Claim-Evidence Graph, base outputs, manuscript, assessment, supplements, role-complete submission files, and reproducibility manifest. Validation reads the frozen copies. The generation, review packet and closure carry analysisGenerationId and a content-addressed material-results manifest; the reproducibility record binds that manifest. A different closed generation, changed report, mixed file parent or changed prepared bytes fails before review. Status/review/closure recheck the current closed lineage and report the affected object and binding. Legacy generations without the manifest retain their history but cannot establish current readiness; prepare an honest binding and refreeze. Computational/mixed analysis still requires reproduced metadata with exact implementation/environment bindings. Qualitative analysis uses status: not-applicable, null command/seed and empty implementation/environment lists; it must not invent a computation. Both paths retain the same evidence, graph, Policy and independent-review checks. Metadata alone is not proof that a computation was executed. Exactly four fresh independent sessions review that frozen generation: evidence, methods/reproducibility, domain/novelty, and journal-editor. A revised manuscript invalidates prior reviews. Every reviewer must use the configured agent family that differs from the native producer; changing only the session ID is not independent. Reviewer-session reuse is rejected from the append-only journal even if mutable cache state is removed. The raw opaque producer/reviewer session identifiers are accepted only at the command boundary; generation, packet, review, journal, and closure objects persist only their SHA-256 bindings.

tiangong-ai research publication lineage top-journal-paper \
  --workspace /absolute/path/to/workspace --json
tiangong-ai research schema show publication-result-lineage --json
tiangong-ai research schema show publication-assessment --json
tiangong-ai research publication freeze top-journal-paper \
  --manuscript /absolute/path/to/final-manuscript.md \
  --assessment /absolute/path/to/publication-assessment.json \
  --submission /absolute/path/to/submission-package.json \
  --producer-agent codex --producer-session OPAQUE_NATIVE_SESSION \
  --workspace /absolute/path/to/workspace --json
tiangong-ai research publication status top-journal-paper \
  --workspace /absolute/path/to/workspace --json

The CLI returns a mechanically bounded ceiling: top-journal-candidate, top-journal-class-ready, or target-journal-submission-ready. Evidence and review failures can only lower it. None of these states predicts or guarantees editorial acceptance.

Before external handoff or archival, export and independently verify a portable audit directory. Export first revalidates the semantic acquisition, content, inference, graph, and publication objects; a copied but stale/tampered chain is rejected. Its manifest exposes their intrinsic IDs and hashes under researchChain. It contains the selected project, portable copies of admitted inputs, formal evidence and artifact bytes, Policy/design/review objects, outputs, environment fingerprints, and safe hash-preserving journal proof derivatives. Credentials, setup sources, browser profiles, native active state, capsules, unrelated projects, and host-specific absolute paths are excluded.

Text inspection distinguishes internal identifiers such as interruptedSessionId from credential fields. It checks raw text and read-only decoded JSON/JSONL, including escaped keys and nested string payloads, while retaining the exact evidence and ledger bytes. Authentication values remain blocked even when wrapped in arrays or objects; an identifier's UUID shape is never a credential exemption. Within the existing 16 MiB per-file text scan bound, valid UTF-8 inputs are also checked after staging under extensionless content hashes. Binary inputs remain byte-preserving. A nonportable-path error reports a bundle-relative details.path without disclosing the original host path or the matched source text.

tiangong-ai research project audit export top-journal-paper \
  --output /absolute/path/to/new-audit-directory \
  --workspace /absolute/path/to/workspace --json
tiangong-ai research project audit verify \
  --bundle /absolute/path/to/new-audit-directory --json

research setup status --json reports credential persistence separately from readiness. It also reports the effective exact-npx CLI package/version/root, the selected project orchestrator, any temporary recovery shim, ignored global same-name Skills, legacy wrappers that still contain an unmanaged PATH CLI fallback, and the real failed source/immutable ref/cache state when checkout is retryable. A direct research search inside a managed workspace stops before network access and returns the same broker-vs-standalone and setup provenance; it never converts a stored broker credential into an ambient credential.

The default internet-research profile selects Brave Web Search and News Search. internet-research-with-context additionally selects the subscription-dependent LLM Context endpoint, while internet-research-with-media also selects image and video discovery. A provider-plan or authentication failure blocks the selected profile instead of silently dropping a Skill. credential set accepts exactly one of --prompt, --from-stdin, or --from-env <name> and stores the value under the declared logical ID; the value is never returned or journaled. For example:

tiangong-ai research setup credential set \
  --id brave.search.api-key --prompt \
  --workspace /absolute/path/to/workspace --json

op read 'op://Research/Brave/api-key' | \
  tiangong-ai research setup credential set \
    --id brave.search.api-key --from-stdin \
    --workspace /absolute/path/to/workspace --json

The pinned Brave checkout is verified at skills/<skill-name> before install. An explicitly reviewed replacement plan reconciles the complete setup-managed capability set and both owner-only credential stores: deselected Brave, SCI, report, or patent declarations and lock records are removed, custom capability declarations are preserved, and installed Skill directories are never deleted implicitly. Provider-dependent context/media choices never fall back silently; select the baseline in a replacement plan when that is the intended operator decision.

The interactive Wizard uses restrained semantic colors and section markers only when its terminal output is a TTY. Hidden credential input is not echoed. Set NO_COLOR or TERM=dumb for plain text; --json also disables Wizard styling so structured output never contains ANSI escape sequences. Password managers may preload one line per logical ID with --credential-stdin <id[,id...]>; the remaining Wizard questions use the controlling terminal.

Optional setup entries have explicit roles. Tiangong SCI, report, and patent search are distinct owner-whitelisted POST evidence capabilities with separate logical credentials and discovery scopes; one cannot substitute for another. Document decomposition is an input preprocessor; academic paper download is an acquisition adapter; document and presentation Skills are post-closure authoring only. Run selected preprocessors and acquisition adapters with research setup companion run, then admit their exact hash-bound output separately. Automatic paper OA exhaustion returns an explicit browser handoff and never launches or chooses a browser silently. Paper results require the pinned adapter's identity-verified artifact.v3 manifest: matched document identity must agree between the result and manifest and bind the requested or resolved DOI. PDF/manifest paths, bytes and hashes remain checked independently. Structural-only legacy metadata cannot establish document identity, and successful access does not imply redistribution rights. The paper companion and its setup-doctor preflight both enter the verified Skill through scripts/runtime.py; the CLI never bypasses that lock by invoking fetch.py or importing pypdf from ambient Python. A missing runtime remains an actionable, non-installing failure until the owner explicitly runs the Skill's hash-locked bootstrap. Selected DOCX, PDF, PPTX, and XLSX authoring Skills bind one resolved Python and Node environment, check their complete Python/Node package and external-command matrices, and then run an exact-file functional canary through the installed pinned Skill helpers. The canaries create, validate, extract or recalculate, and render synthetic sentinel artifacts, including the PDF image helpers and both PPTX/XLSX MarkItDown paths, without scanning a directory for a newest file. A failed prerequisite or canary makes only that authoring component BLOCKED; research-core readiness remains independent. Setup reports the minimum owner action and never runs pip, npm, Homebrew, apt, or another dependency installer. For PPT creation, setup recommends hugohe3.ppt-master first; anthropic.pptx remains a compatible situational option, and both may be selected in the same explicit plan.

Every leaf command accepts --help before workspace resolution, so operators can inspect capability doctor, project preflight, project init, and run syntax safely from an empty or unrelated directory.

The requirements object declares dimensions, sourceTypes, optional requiredCapabilityIds, requiredCompanionIds, and requiredDiscoveryScopes, minSources, minFullTextSources, minDatedSources, and optional inclusive publicationDateFrom / publicationDateTo boundaries (YYYY-MM-DD or null). Explicit capability/scope requirements are exact: wildcard web or SCI coverage cannot satisfy a required report database. Preflight returns both stable string gaps and structured coverageGaps with the affected dimensions, source types, alternative-coverage decision, and minimum owner action. After discovery, a mechanical coverage gate verifies the declared source, full-text, publication-date, and dimension summary before analysis. For large local sources, pass an immutable --input-plan to both preflight and project initialization. Each plan entry may expose either a separate contextPath or non-overlapping, one-based contextRanges; the producer sees only that bounded context, while independent review receives the hash-verified full source. Symlinks, duplicate content and changed hashes are rejected. There is no total stage-context length gate: large admitted objects remain complete and are read through the packet's artifact directory instead of being forced into the initial prompt. This does not expose files deliberately withheld by an input plan.

The workspace stores its current protocol state under .tiangong-research/. Each project follows the evidence-first sequence: broad discovery, strict admission, acquisition audit, immutable evidence freeze, analysis, synthesis, independent review, and mechanical closure. Discover, acquire, analyze, and synthesize run in the current interactive Codex, Claude Code, WorkBuddy, or CodeBuddy session. The CLI never launches a nested producer process. Independent review runs through the other configured agent family's CLI, and execution is blocked when the two roles use the same family.

Native packets direct the host to save one new JSON submission file, not to write admitted output paths. Acquire may retrieve files and readable derivatives for provisionally admitted sources through the packet's binding/registration commands; it may not reopen discovery. Analyze, synthesize and the isolated reviewer retain their no-new-evidence boundary. Headless reviewer prompts remain capsule-scoped and return JSON rather than saving native submission files.

Every workspace mutation is serialized by an owner-recorded directory lease with a heartbeat. A later command immediately reclaims a lease whose same-host owner process is definitely dead; an unverifiable cross-host lease is reclaimed only after its heartbeat expires. The CLI also recognizes and safely recovers the single-file lock left by a killed earlier release. Recovery is appended to the workspace journal using only the prior operation, time, reason, and a one-way lock identifier—never a PID, hostname, or host path. A live or unverifiable owner returns RESEARCH_WORKSPACE_LOCKED with a minimum action and must not be bypassed by manually deleting lock state. Idempotent commands such as an already-recorded download bind may then be replayed normally after safe recovery.

Independent reviewer execution always requires /usr/bin/sandbox-exec on macOS or Bubblewrap (bwrap) on Linux. reviewerExecution.transport=native-direct creates that capsule in the current process. sandbox-bridge sends one hash-bound request to an owner-started, exact-version sidecar outside an IDE sandbox; the sidecar creates the same capsule and returns an Ed25519-signed attestation bound to workspace/config/runtime/capsule/request/result/model and policy hashes. The two transports are explicit and never fall back to each other. Windows can inspect and configure workspaces but does not launch reviewer packages; smoke-test setup reports a non-blocking warning there, while production readiness fails closed. The current native producer remains governed by its host application's own permissions; the CLI supplies a hash-bound packet and deterministic broker commands, not a second nested sandbox or agent.

Add immutable local evidence, verify the workspace, and execute ready work:

tiangong-ai research project input add gpu-resource-impact \
  --workspace /absolute/path/to/workspace \
  --path /absolute/path/to/inventory.csv \
  --role primary
tiangong-ai research workspace doctor --workspace /absolute/path/to/workspace
tiangong-ai research workspace doctor --workspace /absolute/path/to/workspace \
  --agent-smoke --capability-smoke
tiangong-ai research run --workspace /absolute/path/to/workspace \
  --project gpu-resource-impact --progress-jsonl
# When stopReason is native-stage-required, perform the returned stage here:
tiangong-ai research project stage prepare gpu-resource-impact \
  --stage discover --host-agent workbuddy \
  --workspace /absolute/path/to/workspace --json
tiangong-ai research project stage submit gpu-resource-impact \
  --session SESSION_ID --output /absolute/path/to/discover.json \
  --confirm-model EXPECTED_MODEL \
  --workspace /absolute/path/to/workspace --json
tiangong-ai research status --workspace /absolute/path/to/workspace --json

For WorkBuddy/CodeBuddy, keep Default Permission and start the sidecar from a separate native terminal with a private non-symlink state directory outside the workspace:

tiangong-ai research reviewer serve \
  --workspace /absolute/path/to/workspace \
  --state-dir /absolute/private/reviewer-sidecar --json

# From the sandboxed IDE:
tiangong-ai research reviewer status --workspace /absolute/path/to/workspace --json
tiangong-ai research reviewer doctor --confirm-agent-smoke-cost \
  --workspace /absolute/path/to/workspace --json

Sidecar readiness includes real filesystem negative probes and a fixed execute|fingerprint|status protocol. It has no arbitrary-command endpoint; reviewer shell, browser, web, undeclared MCP, and Skill tools remain disabled. Do not use Full Access, sandbox-disable flags, unsandboxed-command exceptions, or silent transport fallback.

Before sending reviewer material, inspect research reviewer status --json. The runtime reports the CLI family and configured model alias separately from providerRouting: the configured Claude endpoint origin/source, model-mapping sources and a digest of admitted routing values. Explicit process environment overrides the imported Claude settings.json env allowlist. Approved custom HTTPS gateways remain supported. Doctor's reviewer-configured-routing check is configuration inspection; it does not make a paid model request.

Routing changes invalidate the prior runtime binding before reviewer execution. Unchanged effective routing reuses the existing attestation; missing legacy bindings require an explicit smoke refresh. Status never starts paid checks. Paths, query strings, proxy credentials and mapped provider IDs are omitted from routing receipts. identityVerification=unverified is intentional: a CLI family, model alias, endpoint configuration or successful smoke cannot attest the actual upstream provider/model or historical HTTP destinations. A null endpoint means no supported explicit endpoint was resolved, not an official provider guarantee. Wrappers, proxies and runtime defaults remain outside that identity guarantee. Bridge status identifies transport readiness separately. Execution model and runtime.model retain the configured alias; optional telemetry.reportedModel records the sanitized CLI self-report, with null when absent. A mapped response name does not change the configured runtime identity or require another smoke. It is not independently verified provider identity.

WorkBuddy/CodeBuddy capsule teardown never requests recursive bulk deletion inside the outer IDE. Native stages remove only the single active-session binding, while completed, aborted, handed-off, and reviewer/work-package capsules are retained. The journal records capsuleDisposition=retained-outer-sandbox plus a non-sensitive capsule ID. Native Codex/Claude hosts normally keep automatic capsule deletion. On Linux/WSL, when Claude refreshes an owner-only .credentials.json capsule copy, the CLI persists it through a same-directory atomic replacement only while the configured owner path, real path, mode, and initial hash remain unchanged. Concurrent owner changes or an unverifiable replacement fail closed and retain the capsule with capsuleDisposition=retained-auth-reconciliation plus a non-sensitive capsule ID for owner recovery. Static environment credentials are never written back. No path silently falls back to Full Access, and retained capsules are never reported as active sessions.

The discover packet derives a bounded multi-channel plan from reviewed evidence requirements. Required channels run first; exact repeated requests reuse the project cache without another provider call but still consume a bounded context view; remaining views are spent only on explicit coverage, counterevidence, date, applicability, or full-text gaps. Native Web/Browser leads may be registered as supplemental candidates, but they cannot be admitted until the same canonical URL/DOI has an immutable broker occurrence. Registered inputs are formal candidates under their own content-hash identity. The acquire packet audits every provisional source and registers only explicit files—never a directory or “latest download.” PDF and Office artifacts are structurally verified and content-addressed. A registered binary full file is review-bound but is not counted as producer-readable full text unless an admitted UTF-8 text/JSON/HTML/CSV/Markdown derivative exists. Such a derivative names its registered parent and inherits that parent's canonical source URL; it does not invent a second network-download binding, and a conflicting URL is rejected.

For top-journal work, the frozen scientific design maps every required evidence role to all applicable lawful acquisition routes in the configured environment. Every declared agent route for a required role is mandatory, and every required capability must map to an available locked broker route at preflight. Each broker call carries its exact acquisition_route_id; native activity and download records carry acquisitionRouteId. A missing or mismatched route ID is rejected rather than becoming evidence that a method was tried.

Inspect the live, hash-verified route state before declaring a material evidence ceiling:

tiangong-ai research project access status gpu-resource-impact \
  --workspace /absolute/path/to/workspace --json

Once all agent routes are terminal, the command first recommends assessing required evidence-role coverage. Its ifEvidenceStillInsufficient field is a conditional access/scope action, not a claim that purchase is always necess