@weftlet/toolkit 0.0.0-stage → 0.1.0

package/docs/ADR-007-toolkit-modules.md

@@ -0,0 +1,53 @@
+# ADR 007: organize the toolkit by responsibility
+
+Status: implemented as a behavior-preserving refactor after public release 0.1.0.
+The user requested internal module organization after publication. Additional internal
+dependency rules are proposed/advisory; the existing approved neutral-core gates remain hard.
+
+The extraction baseline retained a flat toolkit source tree. With extraction, graph queries,
+snapshot handling, providers, presentation and governance now present, that layout hid useful
+boundaries. Keep the two-package distribution and give each responsibility an internal module.
+Do not turn directory organization into a new backend migration or public API redesign.
+
+| Module | Responsibility and interfaces |
+| --- | --- |
+| `configuration` | Load/validate portable configuration and resolve cache locations. |
+| `repository` | Read Git evidence, materialize committed trees, select files and identify working content. |
+| `infrastructure` | Process execution, consumer module resolution and shared neutral utilities. |
+| `storage` | Read/write graph snapshots and extraction artifacts; no application orchestration. |
+| `graph` | Evidence authority, RDF representation, queries and diagnostics over supplied evidence. |
+| `extraction` | Prose/providers/citations, TypeScript SCIP, runtime evidence and ontology compilation. |
+| `application` | Assemble adapters and services; orchestrate hydration, saved evidence, overlays and freshness checks. |
+| `interfaces` | CLI/MCP transport, request parsing, setup and diagnostics commands. |
+| `governance` | Translate the canonical policy into dependency analysis and evidence-backed reports. |
+| `visualization` | Render the same queried evidence and viewer interactions. |
+
+The toolkit's internal modules consume the neutral `@launch-echo/tently-core` contracts
+directly. Internal callers import the specific module they need; there are no new blanket
+module barrels or additional npm packages. The small root files preserve the supported
+library, core and telemetry exports and executable locations. Imports into private `dist/`
+implementation paths are not public package exports; the installed-consumer test uses the
+new internal SCIP path explicitly. Public entry points and exported names remain unchanged.
+
+Unit/module tests remain beside the implementation. Cross-module, installation/startup and
+portability tests live in `tests/`; release-helper tests live beside the scripts. The product
+independence test scans nested runtime files recursively. Moving tests must not reduce the
+suite's coverage. A clean build removes obsolete compiled files before compiling either
+package, preventing old flat modules from being shipped beside the new layout.
+
+`architecture.policy.json` now maps individual modules and proposes executable restrictions:
+evidence/infrastructure modules must not depend on application or presentation; graph queries
+must not reach into extraction or persistence; storage and repository must not depend on higher
+evidence modules; implementation must not import the public/CLI entry points. These rules
+exclude test files as import origins so integration tests can exercise several modules.
+Rules are advisory until the owner explicitly approves them. No new approval, baseline or
+exception is inferred from a file move. Historical debt fingerprints and source inventory
+hashes remain intact; inventory destination paths follow moved files.
+
+This does not split large functions, remove complexity findings, change graph semantics,
+change snapshot identities/formats, fix the outstanding native Windows issues or publish
+another npm release. The published 0.1.0 archives remain immutable; this development change
+needs a new version before future publication.
+
+Package naming update: the original `@launch-echo/tently-core` boundary is now `@weftlet/core`;
+see [ADR 008](ADR-008-weftlet-packages.md). This does not change the module decision above.

package/docs/ADR-008-weftlet-packages.md

@@ -0,0 +1,32 @@
+# ADR 008: Weftlet package identity and publishing
+
+Status: accepted by the maintainer, 2026-10-21. Publication and trusted-publisher validation are pending.
+
+Use `@weftlet/core` for neutral contracts and `@weftlet/toolkit` for the implementation, CLI and
+MCP server. Both new package names start at 0.1.0; npm versions belong to each package name, so
+this does not replace or reuse the published Tently archives. The primary executable is `weftlet`.
+Keep `context-graph` and `context-graph-mcp` aliases, configuration paths, graph identities and
+public library exports compatible. Provide `toolkit` as the npm executable-inference alias and
+`weftlet-mcp` as the branded MCP command. The maintainer subsequently renamed the destination
+repository to `jchewitt/weftlet` on 2026-10-21; npm trusted publishing must use the new repository name.
+
+New package scope ownership was confirmed by the maintainer. Previous release evidence remains
+recorded under its actual package names and commits. Preserve the extraction inventory, licenses
+and LaunchEcho attribution; no source repository work is part of this change.
+
+Release through an explicitly dispatched GitHub workflow. A preparation job with read-only
+repository permissions installs, validates and packs the source; an environment-gated publication
+job receives those exact artifacts and OIDC permission without installing project dependencies.
+Archive integrity and source commit are verified before publication. Main-branch restriction,
+serialized runs and configured environment reviewers constrain release initiation and approval.
+The workflow defaults to preparation only. npm configuration must authorize the exact repository,
+workflow and environment separately for each package.
+
+Retain a normal npm login path for the initial publication and local recovery. OIDC mode is
+explicit, requires a supported npm version and GitHub-hosted context, rejects ambient token
+variables, isolates npm user/global configuration and skips `npm whoami`, which does not validate
+OIDC publication rights. The registry verifies the identity; local preconditions are not proof of
+trusted publishing. Publication is sequential and resumable, not atomic across the two packages.
+
+Do not deprecate or unpublish old packages during preparation. Verify public replacement installs
+first. Follow [release instructions](RELEASING.md) and [consumer migration](MIGRATING-TO-WEFTLET.md).

package/docs/CLOUD-ENVIRONMENT.md

@@ -0,0 +1,56 @@
+# Cloud development environment
+
+Destination: `/workspace/tently`, `github.com/jchewitt/weftlet`.
+The checkout mount retains its original name; the GitHub repository was renamed on 2026-10-21.
+Tested: Linux, Node 24.19.0 and pnpm 10.18.2. `scripts/cloud-install.sh` installs the pinned
+package manager into a writable workspace tool directory, sets writable caches, installs the
+frozen lockfile and builds the neutral core/toolkit.
+
+Start each shell session with:
+
+```sh
+export PATH=/workspace/context-graph-tools/node_modules/.bin:$PATH
+export npm_config_store_dir=/workspace/.pnpm-store
+export npm_config_cache=/workspace/.npm-cache
+export XDG_CACHE_HOME=/workspace/.cache
+cd /workspace/tently
+```
+
+Use `pnpm context-graph:publication-check` for the deterministic build/test/governance/license/
+inventory/installed-package gate. It does not publish. Use `node dist/cli.js doctor` to inspect
+readiness. No background web server is required. MCP is a stdio process launched by its client;
+use `node mcp-launcher.mjs` for development, with `CONTEXT_GRAPH_CONFIG` pointing at the consumer
+configuration. Installed clients run `context-graph-mcp` directly.
+
+Saved snapshot queries require no model or Docker. Refresh is explicit and operates on committed
+inputs without changing the active checkout. Draft overlays are a separate explicit command.
+The configured default ontology backend is RDF. Live Codex extraction is blocked here by an
+immediate read-only filesystem error; authenticated login alone did not establish readiness.
+Do not copy credentials or alter the managed CLI home to work around it.
+
+The source was inspected read-only at the recorded SHA in temporary storage. It is not an
+environment project checkout or an application dependency. No source installation, build, service
+restart, branch change or remote write occurred.
+
+The user authorized pushing reviewed destination commits to `jchewitt/tently` on 2026-10-20.
+A fresh Git clone is the portable route for local testing. Cloud environment publication alone
+does not publish repository commits or prove fresh-task restoration; those are separate checks.
+Saving an environment draft does not apply/publish it. Review and activate it through environment
+settings separately from any repository/package publication decision.
+
+Optional npm publication uses the secure `WEFTLET_NPM_TOKEN` environment binding, scoped to
+`registry.npmjs.org`. The older draft may still list `TENTLY_NPM_TOKEN`, which remains supported
+as a compatibility alias. Neither secret is needed for development, validation, local npm login
+or GitHub OIDC publication; no new cloud token requirement was added for the rename. See `RELEASING.md` for the publisher's temporary npm
+configuration and archive verification. No credential value belongs in this repository.
+
+See [environment validation](ENVIRONMENT-VALIDATION.md) for the hosted CI evidence, fresh-task
+restoration procedure and browser-MCP checklist. These checks do not require live Codex.
+
+Current package identity is Weftlet (`@weftlet/core`, `@weftlet/toolkit`). The checkout stays at
+`/workspace/tently`; GitHub is now `jchewitt/weftlet`. GitHub OIDC publishing is configured separately through
+`publish.yml` and the `npm-release` environment; no cloud npm token is required for that path.
+See [releasing](RELEASING.md). Live auth validation remains tentative and non-blocking.
+
+The architecture configuration retains `jchewitt/tently` as its stable graph repository ID.
+This is an evidence identity, not a Git remote; renaming GitHub does not invalidate saved graphs.

package/docs/ENVIRONMENT-VALIDATION.md

@@ -0,0 +1,78 @@
+# Remaining environment validation
+
+macOS is outside the maintainer's current validation scope. Treat the following checks
+separately; a live model provider is not a prerequisite for deterministic development.
+
+## Hosted CI: verified
+
+GitHub-hosted Ubuntu run [39492039168](https://github.com/jchewitt/weftlet/actions/runs/39492039168)
+completed successfully at `92ae118ccb22f59aaa150b1c8f3a009bdacc788a`. Its `deterministic` job
+ran checkout and the repository's composite action. That action selects Node 24 / pnpm
+10.18.2, installs the frozen lockfile and runs the complete publication gate, including the
+packed-consumer smoke. It neither publishes packages nor invokes a live model. Codex/npm
+publication credentials and the managed cloud filesystem are not needed by this job.
+
+## Fresh cloud: requires a new task
+
+Before publishing the current environment snapshot:
+
+1. Commit/push destination work and confirm the reusable install/start instructions are current.
+2. Run `bash scripts/cloud-install.sh` and `pnpm govern` using the shell exports in
+   `CLOUD-ENVIRONMENT.md`.
+3. Run `node scripts/check-restoration.mjs --checkpoint`, then `--verify` as a local rehearsal.
+   This retains a public repository snapshot, its digest and a query configuration with an
+   intentionally unavailable model provider under ignored `.context-graph/`.
+4. Save/publish the environment configuration through the cloud UI. A draft save alone does
+   not apply it or create a restored environment.
+
+Open a genuinely new cloud task using that published environment and this destination repo.
+An additional shell or a fresh clone in the same machine does not establish platform restoration.
+Give the new task this instruction:
+
+> Validate restoration using docs/ENVIRONMENT-VALIDATION.md. Record the actual environment,
+> repository SHA and tool versions. Before rebuilding or running governance, run the saved
+> evidence verification. Do not regenerate a missing checkpoint, install missing dependencies,
+> call a model, publish packages or change tracked files to conceal a restoration failure.
+> Then run the deterministic publication gate and record results and missing prerequisites.
+
+In that new task:
+
+- Check cwd/origin/SHA, Node 24+, pnpm 10.18.2, dependency availability and writable workspace
+  caches. Apply the saved shell exports, without assuming exported variables or processes survived.
+- Run `node scripts/check-restoration.mjs --verify` **first**. It checks the saved content hash
+  and queries that exact snapshot despite the unavailable provider. Historical/configuration
+  mismatch evidence must remain ineligible for current-diff validation. Missing retained files
+  are a restoration result, not permission to regenerate proof.
+- Run `pnpm context-graph:publication-check`. Record the tested SHA, results and optional skips.
+  This rebuilds and exercises real SCIP, RDF/SHACL, snapshots, CLI/MCP and installed consumption.
+- Record whether the environment actually came from a new task. Passing the rehearsal here
+  establishes only current-instance behavior.
+
+MCP is a client-launched stdio process; it must initialize afresh. No background web process
+is required to survive restoration. Current tools do not let this agent create/publish a new
+cloud instance; the user launches that final validation task through the cloud UI.
+
+## Browser: run through browser MCP
+
+Browser MCP is not attached in the current task. It can be attached to a browser-capable task
+or run on HDesk. Use public evidence and generate a fresh HTML viewer with the corresponding
+CLI JSON Context Pack. Keep the tested SHA, snapshot ID, JSON and HTML together. Serve it using
+the browser tool's supported local/forwarded access; do not assume another machine's localhost
+is reachable.
+
+Check node selection by mouse and keyboard, detail/citation rendering, authority and cluster
+filters, neighbor drill-down, directed path highlighting and the explicit no-path result.
+Check commit/scope/coverage/staleness and truncation indicators against the JSON pack; an absent
+path in a bounded page must not be presented as proof of no dependency. Check configured source
+links, browser console errors and network failures. Capture screenshots/results and browser
+version. Rendering HTML or testing its JavaScript functions alone does not establish interaction.
+
+## Live Codex: separate remaining environment issue
+
+The HDesk live Windows pass remains valid for its recorded commit/tool versions. The managed
+cloud's earlier read-only-filesystem failure is still unresolved. First isolate CLI startup,
+supported writable paths and managed runtime requirements using redacted diagnostics; do not
+copy credentials or change the managed CLI home. Use a minimal public fixture and an explicit
+model budget for a later live retry. A fresh-task live failure should be recorded separately
+from successful deterministic restoration. HDesk can validate the adapter and browser behavior,
+but cannot prove that a different hosted environment restored correctly.

package/docs/MIGRATING-TO-WEFTLET.md

@@ -0,0 +1,54 @@
+# Migrating from Tently to Weftlet
+
+The project is now Weftlet. LaunchEcho remains the maintainer; the GitHub repository remains
+[jchewitt/weftlet](https://github.com/jchewitt/weftlet). Check [release status](RELEASING.md) before
+installing the new names: source preparation is not proof of public npm availability.
+
+| Previous package / command | Replacement |
+| --- | --- |
+| `@launch-echo/tently` | `@weftlet/toolkit` |
+| `@launch-echo/tently-core` | `@weftlet/core` |
+| `tently` | `weftlet` |
+| `context-graph` | Still supported; `weftlet` is the primary CLI |
+| `context-graph-mcp` | Still supported; `weftlet-mcp` is the primary MCP binary |
+
+After the new release is public, replace the old dependency using your package manager. For
+an npm project that installed the toolkit as a development dependency:
+
+```sh
+npm uninstall @launch-echo/tently
+npm install --save-dev @weftlet/toolkit
+npx weftlet config validate
+npx weftlet doctor
+```
+
+If core was a direct dependency, replace it with `@weftlet/core` using the same dependency type
+as before. If it was transitive, the toolkit brings it in automatically. Update library imports:
+
+```ts
+import { ContextGraphHydrator } from '@weftlet/toolkit';
+// Existing /core and /telemetry toolkit subpaths remain available under @weftlet/toolkit.
+```
+
+Change `@launch-echo/tently-core` imports to `@weftlet/core`. Public export names are retained.
+Update scripts and MCP client commands. A fresh npx invocation uses:
+
+```sh
+npx @weftlet/toolkit init
+npx --yes --package @weftlet/toolkit weftlet-mcp
+```
+
+Keep `CONTEXT_GRAPH_CONFIG` pointing to your existing configuration. Do not rerun `init` over
+an existing project. `context-graph.config.json`, `.context-graph/`, schema versions, ontology
+identities and saved evidence formats do not change for this rename. Existing semantic artifacts
+are not invalidated just because the npm package names changed. CLI `toolkit` is also shipped
+so npm can infer an executable from the scoped package basename; use `weftlet` in your own scripts.
+
+Weftlet includes the post-Tently module organization and explicit Codex authentication selection.
+ChatGPT login is the default, while API authentication is opt-in. Live authentication validation
+is tentative and non-blocking, as accepted by the maintainer; see [providers](PROVIDERS.md).
+Native Windows limitations remain documented in [validation](VALIDATION.md).
+
+The old `@launch-echo` releases remain immutable and usable. Do not unpublish them. Deprecation
+is a later registry action, only after both replacements and a fresh public installation are
+verified. This migration does not modify or reintegrate the original TradePilot repository.

package/docs/PROVIDERS.md

@@ -0,0 +1,121 @@
+# Semantic provider contract
+
+Codex CLI is the shipped model adapter. The module extension contract is tested with deterministic
+providers; no additional CLI or API integration is advertised as working. An arbitrary executable
+is not compatible merely because it accepts stdin.
+
+`SemanticExtractor` has a stable `identity` and
+`extract(source, context, {signal, timeoutMs}) -> {parsed, rawModelOutput}`.
+The exported `SemanticOutput`, `semanticOutputSchema` and `assertSemanticOutput` define structured
+assertions, node kinds, predicates, inclusive source citations, finite confidence and diagnostics.
+Every provider passes the same runtime checks before artifacts are saved. Deterministic OML is
+rendered from accepted assertions; model-proposed OML never becomes executable ontology.
+Evidence authority is assigned by source approval policy, never by the provider.
+
+Codex receives a single numbered public or explicitly selected local document in an isolated
+temporary directory. Shell tooling, user config and rules are disabled; authentication remains
+managed by the installed CLI, with the explicit authentication selection below. The child
+inherits only the explicit environment allowlist and, in API mode, the selected API key.
+Prompts, provider stderr and credentials are never printed by progress/error handling.
+Artifact storage contains model output and must remain private with the source repository.
+
+## Codex authentication
+
+Status: implemented in unreleased source; live validation is **tentative and non-blocking for
+release**, as accepted by the maintainer. Follow-up is planned after publication and adoption into
+Banditrade using the maintainer's existing ChatGPT login; API-key testing may remain deferred.
+The earlier `@launch-echo/tently@0.1.0` release does not contain this option. Both modes still use Codex CLI;
+this is not a direct OpenAI API provider or a fix for the managed-cloud filesystem issue.
+
+Merge one of these fragments into your existing `context-graph.config.json`:
+
+```json
+{ "semantic": { "provider": "codex-cli", "auth": { "mode": "chatgpt" } } }
+```
+
+Omitting `auth` also selects `chatgpt`; `init` writes it explicitly. Sign in using `codex login`
+and select ChatGPT. Weftlet checks `codex login status` before an uncached extraction and requires
+it to report ChatGPT login. A missing, unrecognized or API-key login fails before model execution.
+There is no automatic API fallback. Existing saved API logins are not changed or logged out by
+Weftlet. The status probe has a maximum five-second timeout in addition to the extraction timeout.
+This mode uses your plan's Codex allowance and limits.
+
+```json
+{
+  "semantic": {
+    "provider": "codex-cli",
+    "auth": { "mode": "api-key", "apiKeyEnv": "WEFTLET_CODEX_API_KEY" }
+  }
+}
+```
+
+API mode uses separately billed API access. Supply the named variable through your local secret
+manager or trusted automation environment. `apiKeyEnv` defaults to `CODEX_API_KEY` when omitted.
+Weftlet passes only the selected key as `CODEX_API_KEY` to `codex exec`, which supports per-invocation
+API authentication without an interactive login. Missing or blank keys fail without falling back
+to saved authentication. A key's presence does not establish validity, model access or available
+quota. Authentication failures do not trigger a switch to the other mode.
+
+Never put a key value in JSON. Unknown `auth` fields are rejected, and this option is only valid
+for `codex-cli`. Ambient `OPENAI_API_KEY`, `CODEX_API_KEY` and `OPENAI_BASE_URL` are not inherited
+implicitly. To use `OPENAI_API_KEY`, explicitly name it in `apiKeyEnv` in API mode. Custom API
+endpoints are not part of this change. Proxy and CA settings remain supported.
+
+`doctor` reports the selected mode, ChatGPT login status, or API key presence. API mode reports
+`key-present-unverified` and `codexAuthenticated: null`; it never makes a paid authentication probe.
+Status output and credential values are not logged. Authentication does not change built-in
+semantic artifact identity, so selecting another mode or rotating a key does not force extraction
+of unchanged documents. Querying saved snapshots does not require authentication.
+
+Ordinary deterministic CI needs neither mode. Keep live semantic CI opt-in and restricted to
+trusted inputs, with narrowly scoped secret exposure and small document budgets. OpenAI's
+[automation documentation](https://developers.openai.com/codex/noninteractive/) describes
+`CODEX_API_KEY` and recommends its Codex GitHub Action for protected API authentication in Actions.
+Compatibility with that action's proxy is not validated here. Trusted persistent runners can
+continue using their ChatGPT login; this change does not provision or copy account sessions.
+
+## Limits and reuse
+
+Defaults are at most 8 documents per hydration, 64 KiB per source, a 120-second timeout per
+request, no retries, and the configured concurrency (validated at 1–4). Source budgets are checked
+before any model call. `maxDocuments`, `maxSourceBytes`, `timeoutMs`, and `retries` may be configured
+within validated limits. Review scope and cost before raising them; these byte/document limits
+are not dollar or token estimates. Ask the operator before substantial paid runs.
+Only explicit transient exit status 75 is retryable, at most twice; authentication, invalid
+output, cancellation and ambiguous failures are not retried. Ctrl-C cancels live CLI extraction.
+Indexing cancellation is checked between phases, not inside the indexer process.
+
+Cache identity includes provider/model/reasoning effort, prompt and contract versions, source
+digest/stable ID, extractor/adapter/ontology versions, confidence threshold and unresolved policy.
+Unchanged artifacts are reused; forced revisions are separate. Failures never replace a valid
+snapshot. Progress shows phase and counts on stderr, with no document text or paths.
+
+For a trusted local provider module, set `provider: "module"`, `providerModule` to a local path
+(relative to the repository root) or installed package, and `providerIdentity` to its exact
+declared version. Packages resolve from the consumer repository using ESM import conditions.
+Export `createSemanticExtractor(config, {signal, timeoutMs})`; the optional second argument passes
+cancellation through asynchronous initialization. One deadline covers module import, factory
+initialization and extraction. Cancelled initialization cannot populate the extractor cache or
+start extraction later. All semantic configuration contributes
+to this adapter's cache identity. Loading happens only during extraction, so a missing module does
+not disable queries. Implement cancellation and cleanup when the supplied signal aborts; the
+wrapper limits waiting but cannot forcibly terminate arbitrary in-process code. Use subprocesses
+with bounded execution when strong process termination is necessary.
+
+`context-graph doctor --config context-graph.config.json` reads configuration, Git availability,
+Codex presence/login status, optional Docker readiness and saved default evidence. A login status
+is not proof that extraction can run. In this cloud environment, Codex 0.163.0 reported logged in
+but its tiny public-example invocation exited immediately with a read-only filesystem error.
+Live extraction is therefore unverified here; deterministic adapter, timeout, retry, citation,
+budget and cache tests pass. No private source was submitted in that check.
+
+HDesk subsequently reported a live end-to-end pass at commit
+`6710e9391a6a01345dab5f5be4ae0656e1c9d1ae` on Windows, Node 24.2.0, Codex 0.153.4,
+`gpt-6-astra`/`medium`, using the unchanged adapter and public example. Citation/schema
+validation, real SCIP, RDF/SHACL, snapshot publication/querying and repeat artifact reuse passed.
+See [validation](VALIDATION.md#hdesk-validation-of-6710e9391a6a01345dab5f5be4ae0656e1c9d1ae)
+for counts and scope. Native Windows npm Codex executable discovery still needs improvement;
+this public-example pass does not establish broader semantic quality.
+
+Provider-dependent tests must remain opt-in, use tiny public fixtures, avoid credentials in
+untrusted CI, and record model/version/date separately from deterministic test results.

package/docs/RELEASING.md

@@ -0,0 +1,144 @@
+# Weftlet npm releases
+
+Current source prepares the first `@weftlet/core@0.1.0` and `@weftlet/toolkit@0.1.0` release.
+The maintainer created the `weftlet` npm organization. Neither new package is claimed published
+by this document. The earlier `@launch-echo/tently-core@0.1.0` and `@launch-echo/tently@0.1.0`
+releases remain available and undeprecated; their public installation evidence is in
+[validation](VALIDATION.md). GitHub is now `jchewitt/weftlet`; npm and GitHub owner names need not match.
+
+Live Codex authentication validation is tentative and non-blocking for release, as accepted by
+the maintainer. Deterministic release checks still apply. Native Windows limitations remain
+recorded; use Linux or WSL for the full release gate. See [consumer migration](MIGRATING-TO-WEFTLET.md).
+
+## First publication and maintainer setup
+
+Creating an npm organization does not publish its packages or configure package-level trusted
+publishers. Use an npm account with permission to publish both names in `@weftlet`. The initial
+publication can use the normal npm login/2FA flow below. Once the packages exist, configure each
+package's Settings → Trusted Publisher with the following GitHub Actions identity:
+
+| npm setting | Value |
+| --- | --- |
+| Organization or user | `jchewitt` |
+| Repository | `weftlet` |
+| Workflow filename | `publish.yml` (filename only) |
+| Environment name | `npm-release` |
+| Allowed action | Enable direct `npm publish` |
+
+On GitHub, create repository Settings → Environments → `npm-release`. Restrict deployment branches
+to `main` and configure a required reviewer. A sole maintainer must be allowed to approve their own
+release. Do not rely on the YAML environment name alone: an automatically created environment has
+no review protection until you configure it. No npm token secret is required for OIDC publication.
+Keep npm account 2FA enabled. The package's repository metadata already identifies `jchewitt/weftlet`.
+
+npm trusted-publisher setup is not validated merely by saving these settings. Test with a later,
+intentional versioned publication. Current npm documentation says a new trust configuration must
+be used within two days or it expires; configure it close to the intended release, and reconfirm
+that behavior in [npm's documentation](https://docs.npmjs.com/trusted-publishers/).
+
+## Prepare reviewed archives
+
+Use Node 24 and pnpm 10.18.2 in a clean, committed checkout. The new namespace starts at 0.1.0;
+subsequent content changes require a new version for the affected packages. Update the lockfile
+when changing workspace dependency versions. Never overwrite or republish an existing version.
+
+```sh
+nvm install
+nvm use
+pnpm install --frozen-lockfile
+pnpm release:prepare
+```
+
+This runs build, deterministic tests, architecture checks, extraction inventory, license checks
+and a fresh packed-consumer smoke. The smoke uses a disposable registry for the two local packages,
+exercises npx inference and automatic core installation, and checks SCIP, RDF/SHACL, visualization
+and MCP. No live model or public npm upload is invoked.
+
+Preparation packs with pnpm, resolves workspace dependency ranges and records commit, names,
+versions and SHA-512 integrity in `.release/manifest.json`. Review it, the tarball file lists and
+`docs/extraction-manifest.json`. Existing versions must match the prepared archive exactly;
+unpublished versions receive an npm dry run. A dry run does not establish OIDC authorization.
+
+Both JavaScript pnpm and standalone `@pnpm/exe` are supported. The publisher must find npm's
+JavaScript entry point beside Node. The workflow pins npm 11.21.1; trusted publishing requires
+at least npm 11.5.1. Use the workflow's pinned tools when reproducing CI release preparation.
+
+## Initial or local publication with npm login
+
+From the same clean checkout and reviewed archives, in an interactive terminal:
+
+```sh
+npm login --registry=https://registry.npmjs.org
+npm whoami --registry=https://registry.npmjs.org
+pnpm release:publish
+```
+
+Complete npm's browser/2FA challenge when requested. Do not pipe or redirect the publication
+command: npm needs terminal input and output for the interactive flow. The default `login` mode
+retains npm's normal credentials and uses `whoami`; it does not silently select OIDC.
+
+For an authorized token environment, `WEFTLET_NPM_TOKEN` is supported through a temporary,
+restricted-permission npm configuration containing only the literal variable reference. Legacy
+`TENTLY_NPM_TOKEN` remains accepted if the new variable is absent. Never paste tokens in chat,
+commit them, or provide either token to the trusted-publishing workflow. No cloud secret is needed
+when publication happens from the maintainer's authenticated WSL session.
+
+## GitHub trusted publication
+
+The workflow `.github/workflows/publish.yml` is manually dispatched, main-branch only, and serialized.
+It does not run on pushes or pull requests. From GitHub Actions → **Weftlet release** → **Run workflow**:
+
+1. Select `main`. Leave **publish** unchecked for preparation only. Review the uploaded
+   `weftlet-release` artifact and manifest in the run summary.
+2. For an intentional release, select **publish**. The preparation job runs again on that exact
+   commit, without publishing credentials. Inspect that run's artifact before approving its
+   `npm-release` deployment; a different run's archive is not the approval target.
+3. After configured environment approval, the publish job checks out the same source, downloads
+   those artifacts and runs `node scripts/release.mjs --publish --auth=oidc`. It does not install
+   project dependencies or rebuild the packages. Only this job has `id-token: write`.
+
+Actions are pinned to commits. Neither job restores a dependency cache. OIDC mode requires a
+GitHub-hosted runner, the expected repository/ref/manual trigger and OIDC request variables;
+it rejects ambient npm token variables and isolates user/global npm configuration. npm performs
+actual identity validation against each package's trust settings. `npm whoami` is deliberately
+skipped in OIDC mode because it is not a trusted-publisher authorization check. Unsupported npm,
+missing trust or rejected identity must fail; there is no token fallback configured by this workflow.
+
+npm creates provenance for public packages published from this public repository through OIDC.
+Local publication explicitly disables CI provenance. Prepared artifacts and synthetic OIDC tests
+do not prove that a live trusted publish or provenance verification has succeeded.
+
+## Ordering, delayed visibility and recovery
+
+Before any upload, the publisher validates every archive hash and its source commit. It publishes
+core first, waits for registry visibility and verifies integrity, then publishes the toolkit. An
+existing identical release is skipped; different bytes at the same version stop publication.
+Publication across packages is not atomic.
+
+After npm accepts an upload it may remain invisible while processing. The publisher saves a
+package/integrity-specific `.accepted.json` receipt under `.release/` and retries only public
+metadata reads, up to 21 checks, 15 seconds apart. Only 404 is treated as pending. Never repeatedly
+upload an accepted version. Keep `.release/` and retry `release:publish` later to resume verification.
+A receipt cannot cover a process interruption before it is written; inspect registry state before
+recovery. Authentication, network and integrity errors are not treated as missing packages.
+
+The workflow uploads `weftlet-publication-state`, including receipts, even when publication fails.
+For a processing timeout, recover those exact archives and receipts into `.release/` at the
+manifest's source commit before an authorized local retry. Do not blindly rerun the whole workflow
+while an accepted upload is still processing: a new run starts without the old receipt. Once a
+release is visible, the normal integrity check safely skips its already published packages.
+
+## Verify public installation before retiring old names
+
+After successful publication, use a fresh disposable project:
+
+```sh
+npm init -y
+npx --yes @weftlet/toolkit@0.1.0 init --yes
+npx --yes @weftlet/toolkit@0.1.0 config validate
+```
+
+Use the actual release version for later releases. Verify registry versions and hashes, core's
+transitive resolution, CLI/MCP operation and provenance when applicable. Update release status
+only after those public checks pass. Deprecating the old `@launch-echo` names is a separate registry
+action after replacement verification; never unpublish the old releases.

package/docs/ROADMAP.md

@@ -0,0 +1,53 @@
+# Delivery roadmap
+
+Destination: `jchewitt/weftlet`. Read-only source:
+`launchecho/tradepilot@fda97e0146099543aeaa6b338ef2b0e9fab0d1d6`.
+
+| Milestone | Delivered and checked | Remaining limits |
+| --- | --- | --- |
+| 1. Standalone | Explicit committed inventory, core/toolkit boundary, public examples, build/tests, packed independent consumer and real TypeScript indexing | GitHub exported; both @launch-echo packages published at 0.1.0 and public installation verified |
+| 2a. Saved evidence | Read/refresh separation, commit/config/scope metadata, dirty querying, isolated archives, atomic snapshots validated on Linux/WSL, failed-refresh preservation | Archive LF conversion and bounded atomic head-replacement fixes pass Linux regressions; native Windows confirmation pending; archives reject symlinks/submodules and sizes above 128 MiB |
+| 2b. Draft overlays | Base/content identity, reindexed replacement, delete/rename handling, separate checkout/agent heads | Full implementation reindex; changed prose invalidated pending re-extraction |
+| 3. Unified graph | RDF/SPARQL, SHACL, lossless projection, bounded continuation, six-stage async cross-source fixture, negative extraction/linkage cases | Local SELECT only; 100,000-fact projection bound; no universal language support |
+| 4. Governance | Canonical approved rules, dependency-cruiser/ESLint/jscpd, scoped debt/expiry, transitive inference, optional OML ADR/parity | No active OWL reasoner; live formal compilation unverified; heuristics remain advisory |
+| 5. Providers/DX | Codex adapter, HDesk live Windows public-example pass and cache reuse, CLI init/config and npx setup, tested module contract, validation/budgets/timeouts/cancellation/retries/cache identity, diagnostics/progress | Cloud live run remains filesystem-blocked; native Windows npm executable discovery needs improvement; other real providers planned |
+| 6. Viewer | Same facts as agents, clustering, drill-down, bounded path highlighting, optional commit source links, authority/coverage/staleness | No real-browser automation; bounded pages, not a complete interactive explorer |
+
+HDesk results for `6710e9391a6a01345dab5f5be4ae0656e1c9d1ae` are recorded in
+[validation](VALIDATION.md#hdesk-validation-of-6710e9391a6a01345dab5f5be4ae0656e1c9d1ae):
+WSL passed 114 deterministic tests and all three original MCP startup tests; the native Windows
+subset still has two failures and three fixture exclusions.
+
+The post-release module-organization increment is described in
+[ADR 007](ADR-007-toolkit-modules.md): internal responsibilities have separate directories,
+public entry points remain stable, and proposed internal dependency restrictions are advisory
+pending explicit owner approval. It does not publish a replacement for npm 0.1.0.
+
+The following unreleased increment adds explicit Codex authentication configuration: ChatGPT
+login by default, API-key mode by opt-in, and presence-only API diagnostics. Validation is
+tentative and explicitly non-blocking for release. The maintainer plans follow-up after publication
+and adoption into Banditrade; API-key testing remains optional. No new live model results are claimed.
+See [provider configuration](PROVIDERS.md#codex-authentication) and the validation record.
+
+Native Windows archive conversion, concurrent head-replacement and MCP file-symlink fixes are
+implemented with regression tests; a focused Windows CI job and HDesk rerun must confirm them.
+Next work should be separate, reviewed increments: improve CRLF checkout integrity checks;
+run bounded semantic-quality evaluations; retain the passing hosted Ubuntu CI gate; validate fresh-cloud
+restoration; resolve the cloud-specific live provider block; add browser
+interaction/accessibility tests; benchmark larger RDF graphs; evaluate a second real provider.
+Figma and source-application reintegration are future adapter work.
+
+macOS is outside the maintainer's current scope. Hosted Ubuntu CI passed at `92ae118`;
+[environment validation](ENVIRONMENT-VALIDATION.md) separates the remaining fresh-task and
+browser-MCP checks from the unresolved live Codex cloud issue.
+
+Validation evidence and decisions are in `VALIDATION.md` and the ADR files. Source approval and
+model assertion review are distinct. On 2026-10-20 the user authorized pushing the reviewed
+destination to `jchewitt/tently` for local testing. The subsequent npm request authorizes release
+preparation/publication under `@launch-echo`; the maintainer completed the 0.1.0 release from WSL. Visibility changes and
+TradePilot reintegration remain outside the authorized scope. See [release instructions](RELEASING.md).
+
+The maintainer authorized the Weftlet migration on 2026-10-21. Current source targets
+`@weftlet/core` and `@weftlet/toolkit`, with a `weftlet` CLI and a manually dispatched trusted
+publishing workflow. First publication, npm trust configuration and a live OIDC publish remain
+separate external steps; the earlier Tently packages remain available and undeprecated.