@ciqol/resenv 0.1.0-beta.1

package/docs/maintainer-handoff.md

@@ -0,0 +1,112 @@
+# Maintainer handoff
+
+## Start a session
+
+Open the repository folder as its own Codex project. Use the same checkout for
+local work or create an isolated worktree for a separately authorized task.
+Read [AGENTS.md](https://github.com/ciqol/resenv/blob/beta/AGENTS.md), [CONTRIBUTING.md](../CONTRIBUTING.md) and
+[the release guide](releasing.md). Inspect `git status`, the current branch,
+the push remote and recent commits before changing anything.
+
+The repository is [ciqol/resenv](https://github.com/ciqol/resenv). Authenticate
+GitHub as `titan-ron` using the repository-local credential setup in AGENTS.md.
+`beta` is the sole remote and default branch. Work on a local `titan/*` branch;
+never commit directly on the default branch. The repository stores all source,
+tests, build configuration and operating instructions needed to continue.
+Do not depend on previous chat history or copy credentials between sessions.
+
+## Product contract
+
+- Package: `@ciqol/resenv`; CLI: `resenv`.
+- Node preloads: `--require @ciqol/resenv/resolve` and
+  `--import @ciqol/resenv/resolve`.
+- Public API: `resolve(env = process.env, { replace: false })`. Always return a
+  copy; update the input only with `replace: true`.
+- Let Nx or the caller load dotenv files. Resolve values already in the
+  environment, once before application imports.
+- Doppler is the only cloud provider. Infer it from
+  `doppler://project/config/SECRET_NAME`; that syntax belongs to resenv.
+- Commands require explicit opt-in. Fetched values remain literal, and a
+  failed pass leaves the caller's environment unchanged.
+- Debug selector: `NODE_DEBUG=ciqol:resenv`. Never log secret values, tokens,
+  command text or provider response bodies.
+- Runtime npm dependencies: none. Dotenvx decryption has been removed;
+  `encrypted:` values remain literal.
+
+## Code map
+
+| Path | Responsibility |
+| --- | --- |
+| `src/index.ts` | Resolution API and atomic replacement |
+| `src/preload.ts`, `src/resolve*.ts` | Startup integration and shared preload state |
+| `src/doppler/` | Reference parsing, HTTPS, bounded concurrency, credentials and login |
+| `src/commands.ts` | Explicit shell substitution and process limits |
+| `bin/resenv.ts` | Login, logout and child-process CLI |
+| `rollup.config.mjs`, `scripts/build.mjs` | CJS implementation, shared ESM facades and generated types |
+| `scripts/release-plan.mjs` | Official semantic-release analysis/notes plugins and beta counter |
+| `scripts/publish.mjs` | OIDC staging of the tested archive and post-publication tag recording |
+| `.github/workflows/ci.yml` | Build once, test the archive across runtimes, manually dispatched release |
+
+## Verify changes
+
+Use the exact Node.js version in `.nvmrc` and normal npm lifecycle behavior:
+
+```sh
+nvm use
+npm ci
+npm run audit
+npm run verify
+```
+
+Unit specs live beside source modules and run with Vitest. Process tests live
+in `test/`. Clean-consumer checks exercise CJS, ESM, declarations, CLI and
+preloads against the packed archive. Tests use dummy values and mocked effects;
+do not use a developer's Doppler account or OS credential store as a fixture.
+See CONTRIBUTING for Nx integration checks and benchmarking.
+
+## Recover release state before pushing
+
+Read current state rather than treating a dated handoff as authoritative:
+
+```sh
+gh run list --repo ciqol/resenv --workflow ci.yml --limit 5
+gh release list --repo ciqol/resenv
+npm view @ciqol/resenv versions dist-tags --json
+npm stage list @ciqol/resenv --json
+```
+
+The first intended version is `0.1.0-beta.1` on npm's `beta` tag. The planner
+uses semantic-release's official commit-analysis and notes plugins directly;
+it does not run the full semantic-release engine. Real published release tags
+supply later beta counters. Do not fabricate tags to advance a version.
+
+Publishing is staged: a trusted manual CI dispatch submits the exact archive
+that passed all consumer checks. The `release` environment accepts only `beta`
+and has no GitHub reviewer gate. npm approval with 2FA makes a stage public.
+After public availability and integrity verification, rerun the original
+release job to record its Git tag and GitHub prerelease. Keep `beta` at that
+candidate's commit until this step finishes, unless the maintainer explicitly
+chooses to reject and replace the pending stage. Do not rerun the whole
+workflow to recover an existing stage.
+
+A staged version reserves its version number. To replace an unapproved
+candidate, the maintainer must reject the old stage with npm 2FA before CI
+stages the replacement. Check stage status before retrying an ambiguous result.
+Never publish from a developer machine, add a publishing token, promote a beta
+to `latest`, or delete the whole npm package. The `0.0.0-stage` placeholder must
+remain until a functional beta is public; removing the last published version
+would remove the package and impose npm's publishing cooldown.
+
+## Known limits and follow-ups
+
+- Native Doppler browser login has unit/mock coverage but has not been verified
+  end to end with a fresh account. Linux credential storage has mock coverage;
+  Windows native login/storage is not implemented. Explicit tokens and existing
+  CLI credentials are supported. See [Doppler details](doppler.md).
+- The development release-tool tree has reviewed advisories. Exceptions expire
+  November 9, 2026, and executable guards fail on expiry or drift. Review
+  [release security](release-security.md); never broaden or bypass the policy.
+- This beta has not had an independent security audit. Passing tests or the
+  static maturity checklist does not establish production readiness.
+- Consumer repositories are separate. Keep local links out of their committed
+  package manifests, lockfiles and CI.

package/docs/maturity.md

@@ -0,0 +1,61 @@
+# Maturity evaluation
+
+Evaluated on October 8, 2026 with the Tashtit maturity 0.3.1 catalog, using
+static working-tree evidence only. This measures the catalog's repository
+hygiene rules; it does not certify security or readiness to publish. Tests
+and hosted checks are recorded separately in [validation](validation.md).
+
+## Maturity: 91% (11/120 weight failing)
+
+The maintained source tree scores 100% (0/97 weight failing). The full catalog
+also discovers the generated `dist/package.json`, so its findings are retained.
+
+| Scope | Failing weight | Relevant weight |
+| --- | ---: | ---: |
+| Root npm project | 0 | 41 |
+| Generated distribution | 11 | 23 |
+| Repository hygiene | 0 | 24 |
+| GitHub Actions | 0 | 32 |
+| Total | 11 | 120 |
+
+## Findings
+
+- **High: generated package has no sibling lockfile** (`lockfile-missing`, 8).
+  Evidence: `dist/package.json:2`; no `dist/package-lock.json` exists. A maintained
+  npm project needs a lockfile. This directory is generated from the root's v3
+  lockfile and consumers maintain their own locks; it is not another workspace.
+  Reference: [npm lockfiles](https://docs.npmjs.com/cli/configuring-npm/package-lock-json).
+- **Medium: generated package has no sibling runtime-version file**
+  (`setup-nvmrc`, 3). Evidence: `dist/package.json:2`; no `dist/.nvmrc` exists.
+  Development projects should pin a runtime. The generated package declares
+  `engines.node: >=20` and does not need contributor setup files. The root
+  `.nvmrc` pins Node 24.19.0. Reference: [nvm version files](https://github.com/nvm-sh/nvm#nvmrc).
+
+## Passed checks
+
+- Root: one v3 npm lockfile, no competing yarn lockfile, `.npmrc`, `.nvmrc`, and
+  registry dependencies with exact direct versions. CI uses `npm ci` and
+  normal lifecycle behavior; it does not pass `--ignore-scripts`.
+- Repository: valid CODEOWNERS syntax, README, CONTRIBUTING and `.editorconfig`.
+- CI: a parseable workflow, explicit scoped token permissions, bounded job
+  timeouts, no `pull_request_target`, and pinned remote actions. The GitHub-owned
+  upload action's exact `v7.0.1` tag is permitted by the catalog.
+
+The earlier 88% score included a lifecycle-script finding that is now resolved.
+No dependency installation, build, test, or remote request was used to derive
+this static score.
+
+## Not evaluated by this catalog
+
+- Docker rules: no candidate Dockerfile exists.
+- Repository protections, private vulnerability reporting and maintainer access.
+- License suitability, secret history, provider login, and runtime behavior.
+
+See [public readiness](public-readiness.md) for the separate exposure audit and
+[validation](validation.md) for observed checks.
+
+## Fixable findings
+
+No automatic fix is appropriate. The generated package's broad runtime range
+does not identify a development version to pin, and adding another lockfile
+would misrepresent it as a maintained workspace.

package/docs/public-readiness.md

@@ -0,0 +1,138 @@
+# Public repository readiness
+
+## Follow-up review — 2026-10-12
+
+The repository is now public, with `beta` as the sole remote and default branch.
+CI has staged the first `0.1.0-beta.1` candidate; npm approval and release
+recording are still pending. The accidental public `1.0.0` has been removed,
+and the `0.0.0-stage` placeholder remains. Recheck live state before release work.
+
+Private vulnerability reporting returned `enabled: false` during this review.
+The security policy's reporting prerequisite remains outstanding until that
+setting is enabled and verified. See [the session handoff](maintainer-handoff.md)
+and [validation](validation.md) for current behavior and observed checks.
+The dated transition plan below is historical evidence.
+
+## Approved transition - 2026-10-10
+
+The current release pipeline and launch state are documented in [releasing](releasing.md).
+The release-tool review and expiring advisory policy are in [release security](release-security.md).
+Earlier dated entries below remain historical evidence and are superseded where
+the current release guide describes a different state.
+
+The user approved public visibility, default branch `beta`, and deletion of
+the four older ancestor branch references. A fresh settings snapshot, complete
+Git bundle and verified restore are retained outside the repository. Recheck
+remote heads and ancestry immediately before deletion. Other governance changes
+and PR creation remain outside this transition.
+
+
+Reviewed on October 8, 2026 at `cb6ebe92c3182051a034dd29e192d51a182b5d22`, before
+the accompanying documentation cleanup. Repository: `ciqol/resenv`. Maintainer
+and authenticated GitHub account: `titan-ron`.
+
+## Result
+
+No real credentials or private machine/employer references were identified in
+the reviewed Git history or hosted Actions outputs. The source can become a
+public experimental repository after the remaining decisions below. This does
+not establish npm release readiness or an independent security audit.
+
+The repository remains private. No branch, default-branch, access, protection,
+or visibility setting was changed by this audit.
+
+## Exposure review
+
+- Gitleaks 8.30.1 scanned all 24 commits reachable from the fetched refs. Its
+  nine matches were synthetic Doppler credentials in tests: eight use a dummy
+  marker and one uses an alternative fixture marker with sequential digits.
+  The tests inject provider and credential helpers instead of authenticating
+  those values. No detector exception or history rewrite was added.
+- TruffleHog 3.97.4 scanned the local Git history with network verification and
+  update checks disabled. It reported no credentials. Sandbox process-inspection
+  restrictions produced temporary-cleanup warnings; the scan completed.
+- Reachable-blob inspection found no committed dotenv/private-key files,
+  absolute developer paths, employer references, or private service URLs.
+- All 14 existing Actions log archives and 14 unexpired package artifacts were
+  downloaded into a private audit folder and scanned offline. Gitleaks found
+  no secrets. Package inspection covered 755 regular files across the archives
+  and found no credential files or private developer/employer references.
+- There are no existing issues or pull requests to review for public exposure.
+- The latest pre-cleanup [CI run](https://github.com/ciqol/resenv/actions/runs/37778134741)
+  passed on Linux Node 20/22/24 and macOS Node 24.
+
+Detection tools cannot prove the absence of every secret. No candidate
+credential was sent to a provider to test whether it works. Git history remains
+visible after deleting an ancestor branch. GitHub exposes existing Actions
+history and logs when visibility becomes public; see
+[GitHub's visibility documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility).
+
+## Cleanup prepared
+
+- Ignore local `.idea/` settings without deleting the developer's files.
+- Keep installation and contributor text independent of repository visibility.
+- Include the MIT license and ciqol contributors copyright, selected on October 8.
+  Registry publication remains disabled.
+- Mark historical validation/dependency entries so old APIs and version plans
+  are not mistaken for current usage instructions.
+- Remove unnecessary references to other project names from current docs.
+  Historical commits remain unchanged.
+- Direct security questions from the issue chooser to the security policy.
+- Prepare `beta` as the sole normal release branch on npm's `beta` channel. CI
+  also checks the current `titan/beta` preparation branch until branch cleanup.
+  PR checks and manual dispatch remain; publishing stays disabled.
+- Recalculate maturity: 91% including generated output, 100% for the maintained
+  source tree. These scores do not establish release readiness.
+
+## Remaining decisions and settings
+
+1. **License resolved:** MIT was selected on October 8, 2026, with copyright
+   held by ciqol contributors. The root and generated manifests declare MIT;
+   the [license](../LICENSE) is included in the package archive.
+2. **Branches:** the selected sole normal release branch is `beta`, with npm
+   channel `beta`. A local dry run with only that branch calculated `1.0.0`;
+   another stable branch is unnecessary. Default-branch selection and deletion
+   of the older branches remain pending. See [release preparation](releasing.md).
+3. **Private reporting:** the endpoint returned HTTP 404 while the repository
+   is private. Enable and verify it after the approved visibility transition,
+   and verify the reporting option described in SECURITY.md. It is not yet available.
+4. **Protections:** all branch entries report `protected: false`; the ruleset
+   API returned HTTP 403 under the current private plan. Re-audit effective
+   protections after the transition. No protection policy was applied.
+
+## Proposed transition
+
+This plan is for review. It does not authorize npm publication, collaborator or
+team changes, merge-policy changes, rulesets, or a pull request.
+
+| Branch | Observed head | Action for the beta-only layout |
+| --- | --- | --- |
+| `beta` | Same reviewed source head as the preparation branch | Keep; make default |
+| `titan/beta` | Current preparation branch | Delete after verifying its head is retained by `beta` |
+| `titan/bootstrap-envref` | `b25da7cfe730bfaca0a470d9a31a303cef7d33ad` | Delete branch pointer |
+| `titan/rename-resenv` | `60e70a4e43b39fc9a87379990e4ed44de50726cb` | Delete branch pointer |
+| `titan/prepare-first-release` | `0c313483d7123b8b4afd360b4e8daae58abc4241` | Delete after changing the default |
+
+At the original audit, all three older heads were ancestors of `titan/beta`;
+none contained unique commits. Before deletion, re-check every remote head and
+verify all four older branches are ancestors of the retained `beta` head. Stop
+if any contains newer or unique work.
+
+After the branch decision, obtain explicit approval for the default
+branch, listed deletions, public visibility, and private vulnerability reporting.
+The CI push filter and release docs are prepared for this layout. Apply
+only approved scopes and verify branches, default, visibility, reporting and
+CI by read-back. Keep npm publishing disabled until its separate prerequisites
+are complete.
+
+## Recovery
+
+A private settings snapshot and complete Git bundle are retained outside this
+repository. Bundle verification and a restore into a separate local bare
+repository reproduced all four original remote branch heads exactly.
+
+Restore deleted branch pointers from their recorded SHAs or bundle before
+restoring the old default branch. Visibility can be set back to private, but
+public forks, downloaded code and copied logs cannot be recalled. A settings
+rollback cannot undo public disclosure. Never overwrite newer branch work or
+weaken protections to force a restore.

package/docs/release-security.md

@@ -0,0 +1,134 @@
+# Release-tool security review
+
+Reviewed October 10, 2026. Owner: `titan-ron`. Scope: semantic-release version
+planning in read-only CI. The runtime package has no advisory exceptions.
+
+## Decision and controls
+
+Admit semantic-release 25.0.9, commit-analyzer 13.0.1 and release-notes-generator
+14.1.1 as exact development dependencies for version calculation and notes.
+Use the bounded exceptions in [security-exceptions.json](security-exceptions.json)
+only with the executable controls below. These are engineering risk exceptions,
+not upstream fixes or a clean vulnerability scan. They expire November 9, 2026.
+
+The isolated audit reports 10 high and two moderate affected-package entries.
+Several entries propagate the same underlying finding to their parent packages.
+The final merged installation reports 12 active advisory IDs affecting six distinct packages:
+
+| Package | Reviewed location | Why its affected code cannot execute in the planner |
+| --- | --- | --- |
+| braces | Development dependency of micromatch | Every callable export is replaced by a throwing guard before loading semantic-release. The selected matching calls delegate to picomatch. |
+| brace-expansion | npm's bundled dependency | The unselected npm plugin and its bundled npm module are blocked by a Node resolution hook. |
+| http-cache-semantics | npm's bundled dependency | Same blocked npm module. |
+| ip-address | npm's bundled dependency | Same blocked npm module. |
+| postcss-selector-parser | npm's bundled dependency | Same blocked npm module. |
+| undici | npm's bundled dependency | Same blocked npm module. |
+
+The branch expander calls `micromatch(list, branch.name)`. The analyzer calls
+`micromatch.isMatch(commitField, ruleField)`. Both functions in micromatch 4.0.8
+delegate to picomatch rather than its braces-based parse/expand helpers. Patterns
+are the fixed branch `beta` and the analyzer's reviewed default rules; commit
+fields and remote branch names are matching subjects. Guarding all braces calls
+also prevents a later caller from silently opening the vulnerable path.
+
+Sources: [branch expansion](https://github.com/semantic-release/semantic-release/blob/v25.0.9/lib/branches/expand.js),
+[commit matching](https://github.com/semantic-release/commit-analyzer/blob/v13.0.1/lib/analyze-commit.js),
+[micromatch matching](https://github.com/micromatch/micromatch/blob/4.0.8/index.js),
+[braces advisory](https://github.com/advisories/GHSA-vfj7-8cjw-p6xm).
+
+The guards pin the engine, analyzer, notes generator, micromatch and braces
+versions. Changed versions fail until the control is reviewed. The audit checks
+each advisory URL, exact affected version and development-only lockfile path.
+New findings, runtime occurrences, changed paths and expired reviews fail CI.
+Propagated parent findings do not create additional blanket exemptions.
+`npm audit --omit=dev --audit-level=high` also runs without exceptions.
+
+The planner receives no GitHub write token, npm credential or OIDC permission.
+It reads Git history and actual beta tags locally. The official commit-analysis
+and release-notes plugins are fixed in code; the full semantic-release engine
+is not invoked while beta is the sole branch. An explicit 0.1.0 beta line and
+monotonic counter replace its default 1.0.0 initial version. The publisher does
+not install dependencies or import release tools. It verifies candidate hashes
+and source identity, then stages the tested archive through npm OIDC. Maintainer approval through npm publishes it.
+A rerun verifies registry integrity before recording the computed tag/release
+through GitHub's API. Conventional Commit classification remains upstream.
+
+## Verification
+
+An isolated test blocked direct braces calls and imports of the unselected npm
+and GitHub plugins. Normal and adversarial commit analysis passed with 10,000
+nested brace pairs in subjects and bodies. The planner tests cover
+`0.1.0-beta.1`, unchanged history, and subsequent beta counters using real history in a disposable clone without changing source refs.
+
+An isolated attempt to override npm's bundled vulnerable components did not
+replace their distributed copies. No ineffective override was admitted.
+Standalone patched releases do not establish that the bundled copy is fixed.
+Review and remove these exceptions when the upstream distributions are fixed.
+
+## Dependency admission
+
+- **Need:** automate Conventional Commit analysis and release notes, as selected
+  by the user. Platform APIs do not implement that versioning contract.
+- **Fit:** retain the selected engine rather than switch to release-please or
+  maintain a custom analyzer. Native publication glue preserves the tested
+  archive instead of letting a package-directory plugin repack it.
+- **Health:** registry review recorded monthly downloads of 12,515,497 for the
+  engine, 12,542,138 for the analyzer and 12,802,125 for the notes generator,
+  with three listed maintainers each. Selected release dates are August 5, 2026;
+  January 3, 2025; and May 8, 2026. The older analyzer remains the component
+  required by the current engine. Maintenance evidence is not a security guarantee.
+- **Trust:** the canonical semantic-release repositories match the distributed
+  modules. The isolated installation verified 447 registry signatures and 121
+  provenance attestations; the final merged installation verified 606 signatures
+  and 186 attestations. Registry metadata does not expose individual MFA or
+  independently prove historical ownership continuity; those limits remain.
+- **License:** the three direct artifacts contain MIT license text. The isolated
+  tree's licenses are MIT, ISC, BSD-2-Clause, BSD-3-Clause, Apache-2.0, BlueOak-1.0.0,
+  Python-2.0, Artistic-2.0, CC-BY-3.0, CC0-1.0 and permissive alternative sets.
+  qrcode-terminal's absent SPDX metadata is resolved by its Apache-2.0 LICENSE.
+  Some artifacts express the license in package metadata rather than a separate
+  license file. No reciprocal source-disclosure license was identified. These
+  development modules are excluded from the consumer package.
+- **Capabilities:** filesystem, subprocess and Git access are required for local
+  history analysis. The selected plugin path does not publish, contact npm or
+  post GitHub comments. The isolated tree contains no install lifecycle hooks.
+- **Control:** exact direct versions and the lockfile pin the tree; CODEOWNERS
+  and Dependabot retain ownership and update visibility. The guards and expiring
+  audit policy fail on drift. Removal means deleting the three development
+  dependencies and disabling release planning/publication; local build and
+  consumer verification remain available.
+
+The audit result must remain visible. Do not describe the release-tool tree as
+vulnerability-free, use an audit-wide ignore, or pass it to a privileged job.
+
+## Publishing platform
+
+The publisher uses the npm CLI shipped with the pinned Node.js 24.19.0 runtime
+(npm 11.17.0). That platform CLI also bundles older components affected by
+advisories. npm 12.2.0 was inspected and still distributes affected versions;
+upgrading to it would not remove this risk. The development-only policy does
+not imply that the platform CLI is vulnerability-free.
+
+The staging path uses npm 11.17.0's existing `stage publish` subcommand and
+accepts only the validated archive, with no lifecycle
+scripts in its manifest. It uses a fresh home, configuration and cache, fixes
+the registry to HTTPS npmjs.org, and strips proxy, token and arbitrary npm
+configuration from the child environment. No package-query, login, shell,
+selector or arbitrary URL input is accepted. OIDC is supplied by GitHub for the
+specific repository, workflow and protected environment. Registry and signing
+services remain trusted inputs. This bounds exposure; it is not an upstream
+fix. The publisher checks the policy expiry again when it runs, including on a
+failed-job retry, and rejects platform version drift. Review the platform CLI
+again before November 9 alongside this policy.
+
+## October 12 staging review
+
+The pinned npm platform includes `lib/commands/stage/publish.js`, which extends
+its reviewed publish command and sets `stage: true`. The same fixed tarball,
+registry, OIDC identity and provenance options apply. Approval/rejection remain
+interactive npm operations, outside CI. The publisher validates npm's JSON
+receipt against the candidate's name, version and SHA-512 integrity and records
+only its stage identifier and hashes. It creates no tag while the archive is
+staged or pending registry availability. After approval, rerun the same release
+job: its existing-version path verifies integrity and records the release.
+No dependency version, advisory exception or expiry was broadened.

package/docs/releasing.md

@@ -0,0 +1,143 @@
+# Releases
+
+## Versions
+
+`beta` is the sole remote and default branch. Releases start at `0.1.0-beta.1`
+and use the npm `beta` tag. A beta tag is not promoted to `latest`.
+
+The planner uses semantic-release's official commit-analysis and release-notes
+plugins. Conventional Commits decide whether changes need a release. Each
+releasable update increments the counter from the latest reachable
+`v0.1.0-beta.N` tag; docs-only changes do not release. Breaking changes during
+this experimental line also increment the beta counter. Selecting a stable
+line or another base version is a separate release-policy change.
+
+The full semantic-release engine requires a normal release branch and defaults
+to a first version of 1.0.0. Using its official plugins directly preserves the
+requested sole-beta-branch setup without inventing a stable branch or a release
+that never happened. The base line is declared in `release.config.mjs`.
+
+The development manifest and ordinary local builds stay private. Only a valid
+release plan sets the distribution version and removes `private` before packing.
+Never edit a generated manifest or overwrite a previously shared archive.
+
+## CI pipeline
+
+The [CI workflow](../.github/workflows/ci.yml) builds one archive:
+
+1. **Build:** normal npm installation, runtime/development audits, registry
+   signatures, lint, strict types and colocated Vitest specs. The read-only
+   planner generates the beta version and notes from Git history. Rollup builds
+   it once; npm packs it and records SHA-256 and SHA-512 integrity.
+2. **Consumers:** Linux Node 20, 22 and the pinned Node 24, plus macOS Node 24,
+   install and test the same archive. Checks cover ESM, CJS, types, preloads,
+   CLI, literal secret output and failure boundaries. Nothing is rebuilt.
+3. **Release:** a manual dispatch from `beta` with `publish: true`, after every
+   check passes. The protected job verifies hashes, workflow identity and the
+   current branch head. It installs no project dependencies and runs no package
+   code. `npm stage publish` submits the exact archive through OIDC with
+   provenance and the explicit `beta` tag. The job validates and saves npm's
+   staging receipt; no Git tag or GitHub release is created yet.
+4. **Approval and recording:** the maintainer reviews and approves the staged
+   package in npm using interactive 2FA. Wait for npm to make it available,
+   then rerun the original release job. It verifies the published integrity
+   against the original tested archive before creating its Git tag and GitHub
+   prerelease. It does not stage or publish the package again.
+
+Pushes, PRs and dispatches with `publish: false` cannot stage a package. Release
+jobs are serialized and not cancelled. Artifacts last seven days. A fresh
+workflow run is not a substitute for rerunning the original release job when
+recovering an already staged/published candidate.
+
+## Required setup
+
+The existing npm trusted publisher must match:
+
+| Field | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization | `ciqol` |
+| Repository | `resenv` |
+| Workflow filename | `ci.yml` |
+| Environment | `release` |
+| Permission | `npm stage publish` |
+
+No permanent npm token or direct-publish permission is needed. The pinned
+Node 24.19.0/npm 11.17.0 platform includes staged publishing. New trusted
+publisher configurations must be validated by a successful CI operation before
+the deadline shown in npm settings.
+
+The GitHub environment `release` accepts only the `beta` branch and has no
+required GitHub reviewers. CI submits staged packages; the maintainer approves
+publication in npm. After reading back the branch policy and verifying npm
+setup, set Actions variable `RELEASE_ENABLED=true`. Leave it unset until then
+to prevent a dispatch from creating an unrestricted environment automatically.
+Environment creation or protection changes require explicit authorization.
+
+## Run the first beta
+
+Open [CI](https://github.com/ciqol/resenv/actions/workflows/ci.yml), choose
+**Run workflow**, select `beta`, and enable the staging input. When build and
+consumer checks pass, the release job stages the archive without another GitHub
+approval. Its summary and the `resenv-stage` artifact contain the stage
+identifier and tested integrity.
+
+Review the staged package in npm, then approve it with the stage identifier:
+
+```sh
+npm stage view <stage-id> --json
+npm stage approve <stage-id>
+```
+
+These are maintainer review/approval commands; the archive is built and staged
+by GitHub Actions. OIDC cannot perform the approval step. Wait for npm scanning
+and public availability, then rerun the original release job to record the tag.
+Verify the npm version, `beta` tag, archive integrity, provenance and GitHub
+prerelease. Never infer success from a staging receipt alone.
+
+For a hosted rehearsal, leave the staging input off. Local verification is:
+
+```sh
+npm ci
+npm run audit
+npm run release:check
+```
+
+None of these commands publishes. The planner can generate a non-publishing
+plan with `node scripts/release-plan.mjs /absolute/path/to/candidate-directory`.
+
+## Recovery and old versions
+
+A failed stage operation creates no Git tag or GitHub release. Check npm before
+retrying an ambiguous outcome: a staged version reserves its version number.
+Do not attempt to stage it again while awaiting approval. Approve or reject the
+existing stage through npm. Rejection requires a reviewed replacement candidate.
+
+The original release job accepts an existing public version only if integrity
+matches its candidate. A conflicting archive, changed beta head or conflicting
+Git tag stops recovery. Keep the beta branch at the reviewed commit until the
+release is recorded. If its artifact expires, review recovery separately.
+
+The maintainer removed the accidental `1.0.0` publication. Retain the
+`0.0.0-stage` placeholder until `0.1.0-beta.1` is publicly available and verified.
+With explicit authorization, remove that exact placeholder version and check
+remaining versions and tags. Never unpublish the whole package. npm's unpublish
+policy still applies; deleted versions cannot be reused.
+See [npm's policy](https://docs.npmjs.com/policies/unpublish/).
+
+## Security and platform limits
+
+The runtime package has no npm dependencies or advisory exceptions. The
+release-tool tree has bounded, executable advisory exceptions expiring November
+9, 2026; it is not vulnerability-free. The privileged job does not install that
+tree. See [release security](release-security.md).
+
+Doppler is the only built-in cloud provider. Fresh native browser login has not
+been verified end to end, Linux credential storage has mock coverage, and
+Windows native login/storage is not implemented. Explicit tokens and existing
+CLI credentials remain supported. Commands require explicit opt-in. Dotenvx
+ciphertext is left unchanged. See [Security](../SECURITY.md).
+
+Sources: [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/),
+[staged publishing](https://docs.npmjs.com/cli/v11/commands/npm-stage/),
+[semantic-release branching](https://semantic-release.org/foundation/workflow-configuration/).