opencode-lookout 0.0.0-stage → 0.1.2

package/docs/RELEASE_GATES_PLAN.md

@@ -0,0 +1,67 @@
+# Release assurance implementation plan
+
+## Goal and boundaries
+
+Add fail-closed release validation without publishing a release, installing a
+self-hosted runner or spending on hosted services. Apply the approved naming break
+below. Preserve the installed checkout; work on `feat/release-gates`.
+
+## Authorized naming migration
+
+The maintainer approved a clean naming break, superseding the compatibility
+requirement. New identifiers are `opencode-lookout`, `/lookout`,
+`bin/lookout.mjs`, and `lookout:` markers. No legacy aliases or preference
+migration are required. Do not touch the installed copy, personal configuration,
+or private host storage. Reinstallation is deferred until after remote release.
+
+Tests must cover damaged markers, idempotent load/unload, retained restrictions,
+rejected self-disables, and offline recovery. Public GitHub already uses
+`opencode-lookout`; verify hosted state before delivery. Old restrictions must be
+restored with the old checkout before reinstalling; never silently remove them.
+
+## Execution checkpoints
+
+The maintainer chose the current policy API rather than an adapter for OpenCode
+2.2.1/2.2.2, then approved a support-aware test policy after the first realistic
+matrix test exposed the API change. Controls require V2 2.2.3+. All five versions
+remain mandatory: 2.2.1/2.2.2 must prove read-only inventory, rejected mutations,
+offline lifecycle/recovery, and both terminal browsing flows. Other versions
+must pass full controls and both terminal flows. Unknown versions do not become
+read-only skips. Evidence records and validates each target's profile.
+
+- [x] Quality, dependency remediation, and naming migration: `src/`, `bin/`,
+  existing tests and docs; run `make check` and both isolated terminal cases.
+- [x] Scanner/evidence validation: `scripts/`, failure fixtures in `test/`;
+  reject every finding, error, missing report, and source mismatch.
+- [ ] Docker matrix and hosted gates: discover and exercise five stable versions
+  and the next RC, then validate workflows and repository protection.
+- [ ] Portable editor/agent guidance and final delivery evidence.
+
+## Work units
+
+1. **Quality and documentation:** enable checked JavaScript alongside strict
+   TypeScript, add lint/JSDoc checks, document module contracts, and run `make check`.
+2. **Release evidence:** add tested parsers that reject any scanner finding/error,
+   missing/stale evidence, nonzero test results, and incomplete compatibility sets.
+   Audit all dependency classes and full Git history; never use severity waivers.
+3. **Containers:** discover the newest five stable `@opencode/cli` versions plus
+   the newest RC for the next release when present. Run actual server/TUI flows in
+   isolated local Docker containers, bound to immutable source and CLI artifacts.
+4. **Hosted gates:** run quality, OSS security, dependency/supply-chain, and container
+   compatibility checks on public standard Ubuntu runners. Avoid artifact uploads,
+   caches, paid scanners, and privileged PR jobs. Manual release assessment also
+   requires matching local evidence and human review; it does not publish.
+5. **Governance:** configure single-maintainer protections (zero required external
+   approvals), security settings, release documentation, and explicit support limits.
+
+## Acceptance and failure paths
+
+Test low/unknown-severity findings, scanner errors and empty/malformed reports;
+stale/mismatched source evidence; fewer than five stable versions; a newly
+available RC; failed/missing matrix entries; and container cleanup. A blocked
+upstream dependency is a release blocker, not permission to weaken the policy.
+
+All code needs typed public contracts or checked JSDoc, with side effects and
+failure/recovery behavior explained. A clean result means only no findings in the
+configured checks at that time. It is not a guarantee that vulnerabilities do not
+exist. No new platform or CLI support claim is made until its test passes.

package/docs/RELEASING.md

@@ -0,0 +1,171 @@
+# Repository metadata and releases
+
+The GitHub repository description should explain what Lookout does without
+claiming official OpenCode affiliation or verified security. Use topic tags for
+discovery: `opencode`, `opencode-plugin`, `tui`, `terminal`, `sidebar`, `typescript`,
+and `developer-tools`. Topics are not Git release tags.
+
+## Version and tag policy
+
+Use [Semantic Versioning](https://semver.org/) and annotated Git tags named
+`vMAJOR.MINOR.PATCH`. During 0.x development, describe compatibility changes
+explicitly in the changelog; do not treat a minor bump as a migration plan.
+Prereleases use suffixes such as `v0.2.0-rc.1`. Never move or replace a published
+tag. Create a new version if a release needs correction.
+
+Tags identify reviewed source revisions. They do not publish an npm package,
+certify provider readiness, or install an update for users. There is
+no automatic publishing workflow. v0.1.2 introduces a separate, manually
+dispatched npm workflow; the older source-release tags remain unchanged.
+
+## Release checklist
+
+1. Review the exact commit, including security, compatibility, recovery, dependency,
+   and license impact. Record the maintainer's approval and commit ID in the PR
+   or release notes. Automated review does not satisfy this step.
+2. Update package and lockfile versions together. Move the relevant changelog
+   entries from **Unreleased** to a dated version section.
+3. On the clean candidate, run `make check`, `npm run security`,
+   `npm run test:compatibility`, and `npm run release:check`. Require all hosted
+   CI jobs, including **Release gate**, to pass on that same revision. Record the
+   source digest, CLI versions/artifacts, container architecture, and Node versions.
+   The required **Analyze** checks must come from full `push` or
+   `workflow_dispatch` runs on the candidate, not the separate **PR Analyze**
+   checks. After merging, verify the full checks on `main` too and confirm its
+   source tree is identical to the approved candidate before publishing.
+4. Inspect tracked files and full history for private data. Every configured
+   finding at any severity, scanner error, missing result, stale receipt, or
+   incomplete compatibility result blocks. Do not waive or suppress findings to
+   make a release pass. Fix the root cause or leave the release blocked.
+5. Create a signed annotated tag if signing is available, or an annotated tag
+   otherwise. Confirm the tag targets the approved commit before pushing it.
+   Push only that named tag; do not use a blanket tag push.
+6. Create a GitHub release deliberately, with behavior changes, compatibility,
+   validation, recovery, and known limitations. Do not attach personal config,
+   logs, credentials, or retained test fixtures.
+
+Public repository creation is not an initial release. Leave changes under
+**Unreleased** and omit a release tag until this checklist is satisfied.
+
+## Scanner prerequisites and evidence
+
+Install Semgrep 1.182.0, Trivy 0.76.1, Gitleaks 8.30.1, Docker, and Node 26.4.0+.
+CI installs checksum-verified binaries and uses a digest-pinned
+Semgrep image; see `scripts/install-ci-scanners.sh`. Semgrep rules are downloaded
+from commit `16b9e6d45f10649f6a531ec4838ed9924372c3bc` with a pinned checksum.
+Only JavaScript/TypeScript language security and GitHub Actions security packs
+are selected. React-specific style/i18n rules are not applicable to this Solid TUI;
+registry packs requiring the paid Pro engine are not silently counted as passing.
+The rules retain the upstream Semgrep Rules License and are not vendored as MIT.
+
+All receipts live in ignored `release-evidence/`. Release assessment requires
+receipts no older than 24 hours and re-discovers CLI targets; a new RC invalidates
+an older matrix. Missing tools, registry outages, scanner database failures, and
+nonzero test statuses block instead of falling back to previous success. Re-run
+after correcting the cause. Failed runs must never be presented as passes.
+
+The matrix tests supported behavior, not identical features on every CLI. The
+maintainer-approved profiles are **read-only** for 2.2.1/2.2.2 and **controls**
+for the remaining targets. Read-only cases must prove rejected mutations, safe
+inventory, lifecycle, and both terminal browsing flows. Control cases must prove
+effective skill/MCP/plugin restrictions and recovery as well. Every case must
+pass its explicit profile; any new unsupported CLI blocks until reviewed.
+
+## Single-maintainer hosted protection
+
+Require a pull request, resolved conversations, and successful **Runtime (Node 22)**,
+**Runtime (Node 24)**, **Quality (Node 26)**, **Security**, **Compatibility**, and
+**Release gate** checks, plus CodeQL's **Analyze (actions)** and
+**Analyze (javascript-typescript)**. The CI aggregate does not replace those
+separate hosted CodeQL checks. Each CodeQL job validates SARIF for every finding
+and analysis error after the analyze action succeeds.
+Full scans run on every repository branch push. PR scans remain available as
+**PR Analyze (actions)** and **PR Analyze (javascript-typescript)**, but their
+change-focused results cannot substitute for full-candidate assurance. For a fork
+PR, the maintainer must bring the reviewed candidate onto a repository branch
+and obtain the required full checks; do not bypass protection to merge it.
+Use zero required external approvals: the sole maintainer reviews the exact
+revision. Disable force pushes/deletions and apply the checks to administrators.
+Remote protection must be verified live; this document alone does not enable it.
+
+Only standard public GitHub runners are used. No self-hosted runners, artifact
+uploads, or cache actions are configured. Runner logs still have normal GitHub
+retention. Do not add paid runners or external service requirements implicitly.
+Never reuse a token from conversation history.
+
+## Manual npm publication (v0.1.2 onward)
+
+Preparation does not authorize publication. Obtain exact-revision maintainer
+approval after reviewing packaging, generated TUI, consumer audits and installed
+server/TUI evidence. Complete the GitHub release checklist first, including full
+candidate and post-merge CodeQL. The approved tag and main must have identical
+source trees. Re-run stale hosted checks: every required job must have completed
+successfully within 24 hours. A newer failed or incomplete workflow blocks; the
+validator does not fall back to an older success.
+
+Configure an npm trusted publisher for GitHub owner `sodejm`, repository
+`opencode-lookout`, workflow filename `npm-publish.yml`, environment `npm`.
+Use GitHub-hosted standard runners. Configure the GitHub `npm` environment to
+allow reviewed release tags and require the sole maintainer's approval; do not
+require a second reviewer. Verify these settings live. Give the publisher only
+the required publish permission, not dist-tag administration. No npm token is
+stored in the repository or workflow. See the current
+[npm trusted publishing guide](https://docs.npmjs.com/trusted-publishers/).
+
+**First-package bootstrap remains an account-setup decision.** npm's
+[trust prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust) require the
+package to already exist on the registry. A registry
+404 does not establish ownership, and local `npm whoami` is not an OIDC permission
+check. If package settings are not available for this new name, stop and agree a
+bootstrap procedure with the maintainer. Do not publish a placeholder, use the
+revoked token, silently switch to token publishing, or claim OIDC provenance for
+a local publish. Login/2FA must happen in the maintainer's own terminal or npm UI,
+never by sharing credentials in chat.
+
+### Approved one-time v0.1.2 bootstrap
+
+The maintainer approved publishing the real first `opencode-lookout@0.1.2`
+artifact using the existing authenticated npm login, with 2FA completed privately.
+This is a one-time exception to OIDC publication, not permission to publish a
+placeholder or use the revoked token. It does not waive any quality, security,
+compatibility, signed-tag, GitHub-release, exact-revision approval, or post-merge
+gate above. Record the approved SHA and tested tarball integrity in the release.
+
+Before publishing, verify the registry still has no package, verify account
+identity, and run `node scripts/check-package-evidence.mjs PATH_TO_TESTED_TARBALL`
+on the clean approved checkout with fresh evidence. Publish those exact tarball
+bytes with `npm publish PATH_TO_TESTED_TARBALL --access public --ignore-scripts`
+from the maintainer's terminal. Never send credentials or 2FA codes through chat.
+If publication is interrupted, query the registry before retrying; do not attempt
+to replace an existing version.
+
+This version has **no GitHub OIDC provenance**. Verify its registry integrity
+against the approved artifact and test a fresh registry installation, including
+offline recovery and both isolated terminal modes. After the package exists,
+configure the trusted publisher described above for future versions. Do not
+dispatch the OIDC workflow for the already-published v0.1.2: npm versions are
+immutable. This exception expires after the first successful v0.1.2 publication.
+
+### Subsequent trusted publications
+
+After account setup and exact approval, manually dispatch **Publish npm (manual)**
+on the published tag (not `main`) with `approved_sha` set to its full commit ID:
+
+```sh
+gh workflow run npm-publish.yml --ref vX.Y.Z -f approved_sha=FULL_APPROVED_COMMIT
+```
+
+The workflow verifies the signed annotated tag through GitHub, the non-draft
+GitHub release, the approved SHA and fresh hosted CI/full-CodeQL runs. It installs
+with scripts disabled, reruns security, Docker and release assessment, packs and
+tests the actual tarball, and checks its integrity against Docker evidence. It
+rechecks hosted state immediately before `npm publish --provenance` using OIDC.
+The job has `id-token: write` only for this manual operation; PR CI cannot publish.
+Provenance binds the workflow's tag revision to the artifact, not to human review.
+
+After publication, verify the registry's version, tarball integrity and provenance
+against the workflow output and approved tag. Install the registry artifact in a
+fresh isolated prefix and rerun packed recovery/server/TUI validation before
+claiming npm delivery complete. If the job is interrupted after publication,
+inspect registry state first: published versions are immutable, and the workflow
+rejects an already-present version rather than attempting to replace it.

package/docs/THREAT_MODEL.md

@@ -0,0 +1,176 @@
+# Threat model
+
+## npm publication and consumer boundary
+
+The npm artifact uses a files allowlist and has no install hooks. Its committed
+generated TUI is byte-checked against source and included in security coverage.
+An isolated consumer install must pass the same all-severity audit parser, without
+assuming dependency overrides propagate from this repository. They do not:
+installing `@opencode/plugin` as a consumer dependency reproduced vulnerable
+glob/minimatch transitive resolutions. OpenCode supplies the SDK/UI runtime;
+optional peers document that boundary without installing a second copy. The
+offline CLI needs only jsonc-parser. Host-runtime security remains an OpenCode
+responsibility, not a claim made by a clean Lookout consumer audit.
+
+npm bin symlinks must execute the CLI rather than silently returning success.
+Tests cover missing, malformed and ambiguous configs, edited ownership markers,
+confirmation refusal and recovery while preserving unrelated denies. Only stable
+package paths are owned; direct registry entries and other config layers can
+override a global disable and require separate inspection.
+
+The manual publication job has short-lived OIDC authority in the `npm` environment,
+not a stored npm token. It requires a verified annotated tag at the approved SHA,
+a non-draft stable GitHub release, matching main tree and fresh complete candidate
+and post-merge CI/full CodeQL runs. It reruns local gates and verifies that the
+published tarball hash is the one exercised by Docker. Missing, malformed, stale,
+failed or mismatched evidence blocks publication. Release evidence endpoints
+are queried using validated public GitHub dispatch identifiers; local manifest
+data is compared locally and is not used to construct outbound request URLs.
+Environment/package settings are external controls and must be checked by the
+maintainer before first use.
+Repository write access and compromised dependencies/runners remain trusted risks.
+
+The maintainer-approved first-package v0.1.2 bootstrap uses an existing npm login
+and private 2FA instead of OIDC, because npm requires an existing package before
+trusted-publisher setup. The maintainer's terminal and npm session are additional
+trusted components for this one publication. All release gates and exact-artifact
+checks still apply, but this version cannot claim GitHub OIDC provenance. No
+credential enters repository files, CI secrets, or chat. The exception expires
+after v0.1.2; future versions use the manual trusted-publishing workflow.
+
+PR CodeQL results can omit findings outside the reported changes. Required
+**Analyze** checks therefore come from full branch-push/dispatch scans; PR scans
+use distinct names. A clean PR analysis alone cannot authorize release, and the
+post-merge full scan must pass before publishing. The integration harness keeps
+fixture session responses in memory instead of writing an unused response dump.
+
+The release-preparation dependency update changes only development declarations
+(`@types/node` and `undici-types`), not production dependencies or runtime authority.
+Install scripts remain disabled. Node 22/24 production-only tests still guard the
+offline CLI contract; Node 26 type declarations alone do not prove that contract.
+
+Configuration reads validate the opened descriptor rather than checking a path
+before opening it. No-follow and nonblocking flags reject final symlinks and
+avoid FIFO hangs. Reads are bounded even if a file grows after validation; link
+count, size, mode, and timestamps are rechecked before parsing. This does not
+protect against a hostile owner of the parent directory or remove the documented
+final-check/rename race with an uncooperative external editor.
+
+## Release assurance boundary
+
+Release checks reject every configured finding, regardless of severity, as well
+as scanner errors, missing output, stale receipts, source mismatches, and missing
+compatibility cases. npm audit covers development, optional, and peer dependencies;
+npm signatures checks registry signatures; Trivy checks the lockfile and repository
+misconfiguration; Semgrep uses pinned OSS language/Actions security rules; Gitleaks
+checks full Git history and current nonignored source. No scan is proof of absence
+of vulnerabilities. This does not certify the host OS or an upstream CLI binary.
+
+The repository's `.semgrepignore` overrides default test exclusions: source,
+test harnesses, and fixtures are scanned. Required entrypoint coverage is checked
+explicitly. Only generated output and separately audited dependency code are
+excluded. Downloaded rule fixtures are not project source and must not be scanned
+as if they were part of Lookout.
+
+Rule downloads are SHA-256 checked in memory before tar receives the same bytes
+on stdin. The archive is not saved to disk. Each run extracts into a fresh private
+directory, preventing stale rule files from changing the configured scan. A
+checksum mismatch or extraction failure aborts before any success receipt.
+
+Actions are SHA-pinned and use standard public runners. Repository access is
+read-only except CodeQL security-result uploads (`security-events: write`);
+CodeQL database uploads are disabled. Its Actions and JavaScript/TypeScript
+analyses reject every SARIF result and warning/error, not just scanner failures.
+Explicit `none`/`note` invocation diagnostics (such as successfully extracted
+files) are informational, not findings. Missing or unknown diagnostic levels and
+recorded exceptions still block, as do findings with any level, even `none`.
+Downloads of
+standalone scanner binaries, the Semgrep image, rule archive, and Node base image
+are digest-pinned. CLI versions are discovered dynamically, and npm integrity binds
+each tested binary. A malicious registry, compromised upstream release, or scanner
+blind spot remains a risk. Dependency overrides cross major versions and require
+behavioral tests, not just a clean audit.
+
+Docker test builds need network access to fetch dependencies. Test execution has
+no network, host mounts, Docker socket, elevated capabilities, or personal secrets.
+Fixture provider/tool denials remain mandatory even inside the container. The
+repository and Docker daemon are trusted inputs, not a sandbox for arbitrary
+malicious code. Local receipts are not signed attestations: a user with filesystem
+access can forge them. Exact-revision maintainer review and matching hosted checks
+remain required. No workflow automatically publishes or treats AI review as human
+approval. The approved breaking rename does not claim old ownership blocks;
+restore/unload the previous installation with its own CLI before reinstalling.
+
+## Assets and authority
+
+Protect global OpenCode configuration, existing access restrictions, credentials,
+and unrelated plugins. The server process already runs with the user's filesystem
+authority. Its authenticated clients can call plugin RPCs. Confirmation protects
+against accidental UI use; it is not a sandbox against a malicious authenticated
+client or another plugin running as the same user.
+
+The TUI is not an authority for configuration paths, resource IDs, or management
+eligibility. The server fixes the target path and rechecks the catalog. RPCs are
+not exposed as model tools. No credential APIs are used.
+
+## Threats and implemented controls
+
+| Threat | Control | Evidence |
+| --- | --- | --- |
+| Wildcard disables or arbitrary file writes | Exact ID validation, fixed config path, fixed resource kinds | Config and controller tests |
+| Erasing external policy | Remove only owned blocks; never add allow rules | Config tests |
+| Replay or stale preview | One-use token, 60-second expiry, configuration hash | Controller tests |
+| Two extension writers | Exclusive file lock and atomic replacement | Controller tests |
+| Partial write or stale lock | Temp-file cleanup; preserve original on pre-rename failure; offline recovery | Controller tests and README |
+| Credential disclosure | Display-field allowlist; no raw API errors or configuration in the catalog | Catalog tests |
+| Terminal control sequences in metadata | Strip control characters and bound display strings | Catalog tests |
+| Loss of re-enable path after filtering | Reconstruct disabled rows from owned entries | Catalog tests |
+| Disabling policy enforcement | Built-in plugins and Lookout are read-only in the UI | Config and catalog tests |
+| Broken UI prevents recovery | External load/unload/status/restore commands; no automatic discovery | Lifecycle tests |
+
+The live fixture validates filtering and recovery for all three controllable
+resource kinds. It runs with temporary HOME/XDG directories and denies provider
+and tool use to keep keyboard-test mistakes from starting inference or shell work.
+Terminal logs can contain local paths and session metadata; retained fixtures are
+local debugging artifacts, not shareable evidence. See [Validation](VALIDATION.md)
+for the tested runtime and remaining coverage limits.
+
+Plugin descriptions add read-only access to the exact local plugin source from
+the server catalog, or its direct package manifest. File reads are bounded and
+reject non-regular files and final-component symlinks. Plugin source is never
+executed for metadata extraction. Only an explicit description field/tag is
+returned, sanitized for terminal control characters; errors do not expose paths.
+The catalog, not an RPC caller, selects the source path. An installed malicious
+plugin already has the server user's authority; these checks are not a sandbox
+against that user or plugin. Description metadata is display text, not instructions.
+
+## Limits and review
+
+Public contribution and CI are additional trust boundaries. GitHub Actions run
+untrusted pull-request code without repository write permissions or project
+secrets. Checkout credentials are not persisted, action revisions are pinned, and
+dependency install scripts are disabled. Dependabot proposes updates; it does not
+merge or publish them. Human review must check runtime dependency compatibility.
+Dependency licenses and notices must be reviewed before redistributing bundled
+artifacts; this repository does not publish bundles.
+
+The status-dot and MCP-display change affects presentation only. It adds no RPC,
+configuration write, credential access, or trust boundary. Existing MCP
+restrictions remain intact and can still be removed by offline restore. Green
+dots indicate catalog availability, not successful authentication or execution.
+
+- Global changes can affect active work in other sessions. The preview warns about
+  this; it does not forcibly stop or migrate those sessions.
+- Higher-priority policy can override a local denial. A saved entry is not proof
+  that a resource is blocked. The catalog reports when it remains listed.
+- An uncooperative external writer can race the final hash check. Keep manual
+  config edits separate from Lookout changes.
+- Loaded skill text cannot be removed from an existing conversation.
+- Server-side plugin status does not certify its terminal component is healthy.
+- Managed provenance is not available for every catalog field. Unrecognized
+  sources are read-only instead of being assumed local.
+- Denials are operational configuration, not a sandbox for arbitrary plugin code.
+
+The owner of this local installation owns these residual risks. Human review is
+pending; test results are not human approval. Recheck this model when adding
+resource kinds, file targets, credential access, or remote management.

package/docs/VALIDATION.md

@@ -0,0 +1,99 @@
+# Validation
+
+## Packed consumer validation
+
+`make check` includes `build:check` and `test:package`. The latter packs the actual
+artifact, installs it outside the checkout with `--omit=dev --ignore-scripts`,
+audits its dependency graph at every severity, and exercises the npm bin and
+offline failure/recovery paths with isolated HOME/XDG directories. It rejects
+accidentally installed SDK/build dependencies. Node 22/24 CI runs this too.
+
+The Docker matrix now loads a production-installed tarball from `/consumer`, not
+the harness checkout. The runner packs once into `.build/npm-artifact/` and copies
+those exact bytes into every image; it does not repack with another platform's
+gzip implementation. Each image's tarball must match the local pack's SHA-512
+integrity. The source and package digests are both recorded in compatibility and
+release receipts. Fixture provider/tool denials and both terminal modes remain.
+For a local packed server/TUI case, use:
+
+```sh
+LOOKOUT_PACKED_INTEGRATION=1 LOOKOUT_TUI=1 npm run test:package
+LOOKOUT_PACKED_INTEGRATION=1 LOOKOUT_TUI=1 LOOKOUT_NARROW=1 LOOKOUT_THEME=tokyonight npm run test:package
+```
+
+These tests prove stable-prefix/path loading. They do not prove direct registry
+entry recovery, npm ownership, OIDC authentication or registry publication.
+
+## Repository checks
+
+`make check` runs Prettier, local documentation-link checks, blocking ESLint/JSDoc,
+strict TypeScript with checked JavaScript, and Node's test runner. Unit tests
+cover catalog filtering, literal search, description metadata, ownership,
+reversible controls, malformed config, duplicate keys, protected IDs, expired
+and replayed previews, external edits, symlinks, locks, and offline recovery.
+Release tests reject low/unknown findings, scanner errors, incomplete reports,
+stale/source-mismatched evidence, incomplete matrices, and failed commands.
+Workflow tests keep required full CodeQL checks distinct from PR-only checks.
+The terminal fixture asserts that session responses are not saved to disk.
+
+## Runtime checks
+
+```sh
+LOOKOUT_TUI=1 node test/integration.mjs
+LOOKOUT_TUI=1 LOOKOUT_NARROW=1 LOOKOUT_THEME=tokyonight node test/integration.mjs
+npm run test:compatibility
+```
+
+The first two commands use the installed CLI with fresh HOME/XDG fixtures. They
+deny every provider/tool action and never submit a model request. They exercise:
+
+- Skill, MCP, and local plugin disable/reload/re-enable and filtered-row recovery.
+- Rejection of protected controls; offline unload/load and RPC disappearance.
+- Carbonfox at 150×52 and Tokyonight at 80×36, search, category/state selection,
+  details, cancellation, confirmation, and offline restore; zero inference cost.
+- Native MCP status without duplicate inventory; file-sourced plugin descriptions.
+
+After cancelling a preview, the terminal harness checks the reopened catalog's
+full heading rather than requiring a contiguous search placeholder. A retained
+failure showed the renderer updating only changed placeholder cells. A synthetic
+regression covers that output and rejects unrelated dialogs; cancellation must
+still leave zero owned restrictions, and confirmation and offline restore must
+still change and restore the fixture. This test-only correction does not change
+runtime behavior, permissions, or the threat model's trust boundaries.
+
+The Docker runner discovers the newest five stable V2+ CLI versions plus the
+highest RC of the nearest unreleased version. It fails if discovery or any test
+fails. Each image installs a CLI artifact with verified npm integrity and locked
+dependencies. Tests run as non-root, without network, capabilities, host mounts,
+credentials, or a Docker socket. Only temporary container storage is writable.
+Both terminal modes run for each target; server/recovery checks run in each mode.
+The approved read-only profile for 2.2.1/2.2.2 requires visible inventory, rejected
+enable/disable/apply RPCs, browsing/details, no changed restrictions, and offline
+load/unload. All other targets require full effective controls. These are distinct
+support claims, not silently skipped test steps.
+Reports bind results to source bytes, CLI integrity, and Docker image IDs.
+
+## Evidence and limits
+
+Machine-readable evidence is generated under ignored `release-evidence/`; do not
+commit raw scanner logs or terminal fixtures. See [Release policy](RELEASING.md).
+Read the source digest, target, profile, mode, and exit status together. A passing
+probe or an earlier commit's run is not a passing current release matrix.
+
+The initial five-version run reproduced an ineffective skill restriction on
+2.2.1. Upstream source confirms 2.2.1/2.2.2 use a different policy action; the
+current `skill.use`/`mcp.use` API starts in 2.2.3. The maintainer chose not to add
+an older-policy adapter and approved testing those hosts against a read-only
+support profile. The original failed control test is not counted as passing;
+fresh profile-specific evidence is required.
+
+The old installation is deliberately untouched. Reinstallation is deferred until
+after remote release. Historical pre-rename tests do not establish this revision's
+compatibility. No broader platform/version support is claimed before its matrix
+passes. Linux amd64 hosted results are distinct from local Linux arm64 results.
+
+PTY tests are not pixel-level or accessibility audits. Mouse interactions,
+preference persistence, remote-server behavior, and other terminal sizes still
+need human review. Catalog filtering does not revoke instructions already loaded
+in conversations. Catalog availability proves neither provider authentication nor
+quota. A clean scan means only no findings in the configured checks at that time.

package/package.json

@@ -1,6 +1,105 @@
 {
   "name": "opencode-lookout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "A native-style resource sidebar for OpenCode, with reversible local controls.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sodejm/opencode-lookout.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sodejm/opencode-lookout/issues"
+  },
+  "homepage": "https://github.com/sodejm/opencode-lookout#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "src/",
+    "bin/lookout.mjs",
+    "dist/tui.js",
+    "docs/*.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "CONTRIBUTING.md",
+    "GOVERNANCE.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "bin": {
+    "lookout": "bin/lookout.mjs"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/server.ts",
+    "./tui": "./dist/tui.js",
+    "./rpc": "./src/rpc.ts"
+  },
+  "scripts": {
+    "build": "node scripts/build-tui.mjs --write",
+    "build:check": "node scripts/build-tui.mjs",
+    "test": "node --test test/*.test.mjs",
+    "test:package": "node test/packed.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 0",
+    "test:compatibility": "node scripts/compatibility.mjs",
+    "security": "node scripts/security.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "format:check": "prettier --check 'src/**/*.{mjs,ts,tsx}' 'test/**/*.mjs' 'bin/*.mjs' 'scripts/*.mjs' '*.json' '.github/**/*.yml' '.vscode/*.json' 'eslint.config.mjs' 'opencode-lookout.code-workspace'",
+    "test:integration": "node test/integration.mjs",
+    "test:tui": "LOOKOUT_TUI=1 node test/integration.mjs",
+    "docs:check": "node scripts/check-docs.mjs",
+    "check": "npm run format:check && npm run docs:check && npm run lint && npm run typecheck && npm run build:check && npm test && npm run test:package"
+  },
+  "dependencies": {
+    "jsonc-parser": "3.3.1"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.2.1 <=2.2.6",
+    "@opentui/core": "^0.8.0",
+    "@opentui/solid": "^0.8.0",
+    "solid-js": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode/plugin": {
+      "optional": true
+    },
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  },
+  "overrides": {
+    "glob@>=9 <=14.0.1": "14.0.3",
+    "minimatch@>=7 <11.0.1": "11.0.4"
+  },
+  "devDependencies": {
+    "@babel/core": "7.29.7",
+    "@babel/preset-typescript": "7.27.1",
+    "@types/babel__core": "7.20.5",
+    "babel-preset-solid": "1.9.16",
+    "@eslint/js": "10.0.1",
+    "@opencode/client": "2.2.5",
+    "@opencode/plugin": "2.2.5",
+    "@opencode/theme": "2.2.5",
+    "@opentui/core": "0.8.0",
+    "@opentui/solid": "0.8.0",
+    "@types/node": "26.6.6",
+    "eslint": "10.14.0",
+    "eslint-plugin-jsdoc": "65.4.3",
+    "globals": "17.14.0",
+    "prettier": "3.9.10",
+    "solid-js": "1.9.16",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.72.1"
+  }
+}