opencode-lookout 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+## 0.1.2 — 2026-11-08
+
+- Add an allowlisted npm artifact and a `lookout` executable for stable-prefix
+  installs. Correct executable detection through npm's symlink; preserve the
+  existing checkout invocation and path-owned recovery markers.
+- Precompile the Solid TUI for loading inside `node_modules`; check generated
+  output against source. Declare the host SDK/UI runtime as optional peers rather
+  than installing a second SDK graph with consumer-unprotected dependencies.
+- Test production-installed tarballs, offline failure/recovery, consumer dependency
+  audits, and the real server/TUI matrix. Bind Docker receipts to tarball integrity.
+- Add a manual OIDC publication workflow requiring the exact approved signed tag,
+  published GitHub release, matching main tree, fresh full hosted checks and fresh
+  local release gates. The maintainer approved a one-time authenticated bootstrap
+  for this first npm version; it has no GitHub OIDC provenance. Future versions
+  use trusted publishing after package setup.
+- Match the full catalog heading after cancelling a terminal preview, rather than
+  requiring a contiguous placeholder in changed-cell renderer output. Preserve
+  cancellation, confirmed mutation, and offline recovery assertions.
+
+## 0.1.1 — 2026-11-05
+
+### Fixed
+
+- Remove an unused fixture session-response dump reported by full CodeQL analysis.
+  The isolated terminal tests now assert that the response is not saved.
+- Require full CodeQL scans on candidate branch pushes. PR-only scans use separate
+  check names and cannot satisfy the required full-scan checks. Release procedure
+  also verifies post-merge checks before publishing.
+- Supersede the withdrawn 0.1.0 release, whose PR analysis passed but post-merge
+  full analysis reported the fixture finding. The 0.1.0 tag remains immutable.
+
+## 0.1.0 — 2026-11-05
+
+### Added
+
+- Native-style Lookout sidebar for agents, skills, plugins, commands, providers,
+  and models, with search, category/state filters, details, and pinned entries.
+- Confirmed, exact-ID restrictions for locally controllable skills and plugins.
+- Independent load, unload, status, and restore commands.
+- Plugin-file descriptions in the sidebar, with `missing description` when
+  supported metadata is absent; plugin code is not executed to read metadata.
+- Public MIT-licensed repository, contributor guidance, security policy, CI,
+  issue templates, and dependency-update configuration.
+
+### Changed
+
+- Standardized product and machine-facing names on Lookout: `opencode-lookout`
+  plugin/RPC ID, `/lookout`, `bin/lookout.mjs`, and `lookout:` ownership markers.
+  This is a deliberate breaking rename, without legacy aliases. Restore and
+  unload an older installation using its own CLI before reinstalling.
+- Enabled strict checked JavaScript, typed catalog projections, and blocking lint.
+- Pinned patched glob/minimatch overrides for all affected dependency versions.
+- Aligned development Node declarations with Node 26 using `@types/node` 26.6.6.
+  Production-only offline CLI tests retain Node 22 and 24 coverage.
+- Added fail-closed OSS security checks, source-bound release evidence, dynamic
+  Docker compatibility tests, and portable OpenCode/Copilot/VS Code guidance.
+- Matched native semantic status-dot colors and removed duplicate MCP browsing.
+  Native MCP controls and existing extension-owned restrictions are unchanged.
+
+### Fixed
+
+- Validate opened configuration descriptors and bound reads against file growth,
+  hard-link changes, and stale permission metadata; reject FIFOs and final symlinks.
+- Install runtime-test dependencies with npm 11.19.1 to preserve patched overrides
+  that npm 10 misresolves. Encode complete registry URL components.
+- Extract checksum-verified rules from memory into fresh directories and distinguish
+  informational CodeQL diagnostics from findings without severity waivers.
+
+### Validation
+
+- OpenCode 2.2.5 server lifecycle and reversible-control integration tests.
+- Carbonfox wide-terminal and Tokyonight narrow-terminal keyboard workflows.
+- See [Validation](docs/VALIDATION.md) for exact evidence and known limits.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,20 @@
+# Code of conduct
+
+Help make this project useful and welcoming. Treat people with respect regardless
+of background, identity, experience, or technical ability. Critique ideas and code,
+not people. Accept constructive feedback and acknowledge mistakes.
+
+Harassment, threats, discriminatory language, sexualized content, personal attacks,
+and publishing someone else's private information are not acceptable. Do not use
+project channels for spam or repeated unwanted contact.
+
+This policy applies to issues, pull requests, discussions, and other spaces where
+someone represents the project. The maintainer may edit or remove harmful content,
+warn participants, restrict participation, or ban accounts according to severity
+and repeated behavior. Maintainers are also bound by this policy.
+
+Report concerns to [@sodejm](https://github.com/sodejm). For sensitive incidents,
+request a private contact method in a minimal issue without naming affected people
+or describing the incident publicly. Share details only after a private channel
+is established. The maintainer will limit disclosure to what is needed to address
+the concern. No response-time guarantee is made.

package/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to OpenCode Lookout
+
+Start with a focused issue for substantial behavior or API changes. Bug fixes,
+tests, and documentation improvements can go directly to a pull request. Keep
+unrelated cleanup separate. Contributions are licensed under [MIT](LICENSE).
+
+## Set up
+
+Use Node.js 26.4.0+ and npm for development, as required by OpenTUI 0.8.0.
+Use npm 11 or later to install the lockfile. npm 10 misresolves the patched
+override graph and rejects `npm ci`; do not remove the overrides to work around it.
+Runtime CI installs with npm 11.19.1 while still running tests on Node 22 and 24.
+`make check` also installs and audits the packed artifact in a temporary consumer
+directory. It requires registry access and fails closed on registry errors.
+After editing `src/tui.tsx`, run `npm run build` and review `dist/tui.js` alongside
+the source. `build:check` requires byte-identical output from the pinned compiler.
+The generated TUI is committed so production-only runtime tests can pack the
+same artifact without installing build tools. It remains security-scanned.
+Development uses Node 26 declarations. Do not assume a type-checked Node API is
+available to the offline CLI on Node 22; its production-only runtime tests remain required.
+The offline CLI retains Node.js 22+ support with production
+dependencies only. OpenCode 2.2.5 is needed only for live integration
+tests. The optional terminal harness needs `/usr/bin/expect` (macOS or Linux).
+
+```sh
+git clone https://github.com/sodejm/opencode-lookout.git
+cd opencode-lookout
+npm ci --ignore-scripts
+make check
+```
+
+Do not load an unreviewed contribution into your personal OpenCode environment.
+Use `npm run test:integration` or `npm run test:tui`: these start an isolated server
+with temporary HOME/XDG directories and deny provider and tool use. See
+[Validation](docs/VALIDATION.md) for the runtime matrix and limitations.
+
+## Make a change
+
+1. Create a focused branch. Reproduce a behavioral bug with a test when practical.
+2. Preserve the plugin ID, RPC contract, configuration markers, and offline
+   recovery commands unless a migration has been explicitly agreed.
+3. Use typed TypeScript contracts and JSDoc for exported JavaScript behavior.
+   Explain non-obvious constraints and failure paths, not routine assignments.
+4. Update affected user and architecture docs. For security-sensitive changes,
+   update the [threat model](docs/THREAT_MODEL.md) and test failure/recovery paths.
+5. Run `make check`. For UI or config changes, also run both terminal cases in the
+   validation guide. Do not describe unavailable checks as passing.
+6. Review the diff for credentials, personal paths, transcripts, and unrelated
+   edits. Never commit retained test fixtures or global OpenCode configuration.
+7. Submit a PR with the behavior change, evidence, compatibility impact, and
+   recovery procedure. A maintainer reviews the exact revision before merging.
+
+Format source with the pinned Prettier version:
+
+```sh
+npm exec -- prettier --write 'src/**/*.{mjs,ts,tsx}' 'test/**/*.mjs' 'bin/*.mjs' 'scripts/*.mjs' '*.json'
+```
+
+## Dependencies and CI
+
+Keep the SDK and OpenTUI versions aligned with the tested OpenCode release. Commit
+`package-lock.json`; install with scripts disabled. Explain new dependencies and
+their trust implications. CI checks quality on Node.js 26 and runtime tests with
+production dependencies on Node.js 22 and 24. The Docker job
+exercises real OpenCode loading and terminal workflows; it does not prove provider
+authentication or pixel-level rendering. All security severities block release.
+
+GitHub Actions use pinned revisions and read-only repository permissions, except
+the existing CodeQL job's `security-events: write` permission to upload scan
+results and the manual npm job's `id-token: write` for trusted publishing.
+Do not add secret-bearing PR jobs, `pull_request_target` execution of
+contributor code, or automatic publishing. AI-assisted contributions have the
+same testing, attribution, security, and human-review requirements as other work.
+
+## Agent and editor development
+
+OpenCode reads `opencode.json` and the shared `AGENTS.md`/contributor guidance.
+Copilot's repository instructions point to the same contract. Neither adapter
+selects models, grants permissions, loads this plugin, or installs MCP servers.
+
+Open `opencode-lookout.code-workspace` in VS Code, review Workspace Trust, and run
+**Lookout: install** yourself. Accepting recommended extensions is optional.
+Tasks cover checks, lint, tests, Docker compatibility, security, and release
+assessment. Tasks do not run on workspace open. Use the workspace TypeScript
+version after installation. Terminal tests need Linux/macOS; use Docker on other
+hosts. No editor task loads the plugin into personal configuration.
+
+## Dependency remediation
+
+The lockfile overrides vulnerable `glob` 9–14.0.1 with 14.0.3 and `minimatch`
+7–11.0.0 with 11.0.4. These major-version overrides address
+GHSA-3g3m-2fjr-6pw4 and GHSA-g3hv-75wg-m249; they are not severity waivers.
+Older unaffected majors are not replaced. `make check` and actual server/TUI
+integration must pass after each override change. Remove an override only when
+the upstream graph resolves patched versions and the full checks still pass.

package/GOVERNANCE.md

@@ -0,0 +1,20 @@
+# Governance
+
+OpenCode Lookout is maintained by [@sodejm](https://github.com/sodejm). It is an
+independent community extension. The maintainer owns scope, compatibility,
+dependency, security, and release decisions.
+
+Use issues for proposals and pull requests for reviewable changes. Explain the
+problem and relevant trade-offs before proposing broad API or configuration
+changes. The maintainer makes the final decision and records material decisions
+in the issue, PR, or affected architecture documentation.
+
+The maintainer may review and merge their own contributions; a second reviewer is
+not required. Automated checks and AI reviews supplement human review, not replace
+it. Human review must cover the exact revision and its failure/recovery behavior.
+
+The repository is public, but npm publication is deliberately disabled. There is
+no automatic release workflow. A future release needs a versioned changelog,
+current validation evidence, security review, and a deliberate maintainer decision.
+Pushing a commit is not a release or proof of compatibility with a new OpenCode
+version. MIT governs reuse; this document governs project contributions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenCode Lookout contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+# OpenCode Lookout
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/sodejm/opencode-lookout/actions/workflows/ci.yml/badge.svg)](https://github.com/sodejm/opencode-lookout/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Inspect agents, skills, plugins, commands, providers, and models in
+OpenCode's terminal interface. The extension appends a compact section to the
+existing sidebar. It does not replace Context or MCP status.
+Use OpenCode's native MCP section or `/mcps` for MCP inventory and controls.
+
+Lookout is an independent community extension, not an official OpenCode product.
+It uses the public OpenCode **2.2.5** API contract. Use Node.js **26.4.0+** for a full development install;
+the offline CLI retains **Node.js 22+** support with production dependencies.
+The repository is public under the MIT license. npm publication is a separate,
+manually approved release operation. See the support profiles below before using
+another CLI version.
+
+Resource controls require the current V2 policy API (OpenCode 2.2.3+). Older or
+unidentified hosts show a read-only inventory. Release tests require verified
+read-only behavior on 2.2.1–2.2.2 and full controls on newer supported V2 hosts.
+
+## Install
+
+### npm package (v0.1.2)
+
+These commands are for use **after v0.1.2 is published**. Install to a dedicated,
+stable prefix, not into another application's dependency tree:
+
+```sh
+mkdir -p "$HOME/.local/share/opencode-lookout"
+npm install --prefix "$HOME/.local/share/opencode-lookout" --save-exact --omit=dev --ignore-scripts opencode-lookout@0.1.2
+"$HOME/.local/share/opencode-lookout/node_modules/.bin/lookout" load
+"$HOME/.local/share/opencode-lookout/node_modules/.bin/lookout" status
+```
+
+Use that same executable for `unload` and `restore --yes`, even when OpenCode
+cannot start. The package does not need development dependencies or install
+scripts. OpenCode supplies its SDK and Solid/OpenTUI runtime; these are optional
+peers, not dependencies installed for the offline CLI. The TUI is precompiled
+because OpenTUI does not transform JSX in `node_modules`.
+
+Do not use `npx lookout` or an ephemeral npm-exec install for lifecycle commands:
+the owned load entry points to the executable's installed package directory.
+Keep that directory until you have restored restrictions and unloaded Lookout.
+Before switching from a checkout, use the old checkout's `restore --yes` and
+`unload`, then use the new executable's `load`. No personal installation is
+migrated automatically.
+
+Direct `opencode plugin add opencode-lookout@...` entries are not owned by the
+offline lifecycle CLI. Do not combine them with the marked path entry. To switch,
+remove the exact unmarked entry through OpenCode first (and check project configs
+for duplicate loads). This release validates the stable-prefix installation,
+not recovery from OpenCode's registry cache. See [recovery](#load-or-unload).
+
+### Source checkout
+
+Clone outside OpenCode's automatically discovered `plugins/` directory:
+
+```sh
+git clone https://github.com/sodejm/opencode-lookout.git
+cd opencode-lookout
+npm ci --ignore-scripts
+make check
+node bin/lookout.mjs load
+```
+
+Create your global OpenCode configuration through OpenCode first if it does not
+exist. Lookout requires exactly one `opencode.json` or `opencode.jsonc` there;
+it will not create a new config or choose between two files. Keep the checkout
+at its installed path, because the load entry refers to that directory.
+
+**Breaking rename:** this revision uses `opencode-lookout` as the plugin/RPC ID,
+`/lookout` as the command, and `lookout:` ownership markers. There are no legacy
+aliases. Before replacing an older installation, use its own recovery CLI to
+restore its restrictions and unload it. Do not run both copies. Reinstall only
+after the remote release is complete; pins and collapsed sections start fresh.
+The new CLI does not claim or remove old ownership blocks.
+
+## Load or unload
+
+Run these commands **from this package's directory**, outside OpenCode:
+
+```sh
+node bin/lookout.mjs load
+node bin/lookout.mjs status
+node bin/lookout.mjs unload
+```
+
+The commands work without the extension, server, or TUI running. They change one
+marked entry in your global `opencode.jsonc` or `opencode.json`. They refuse to
+choose between those files if both exist. They respect `XDG_CONFIG_HOME`.
+
+OpenCode watches configuration changes. Use `/reload` if the UI has not updated.
+`status` reports the configuration on disk, **not** whether the extension loaded.
+Check `opencode plugin list` and open `/lookout` to verify both parts.
+
+Unloading keeps resource restrictions in place. Removing a UI must not silently
+restore tool access. To remove restrictions created by this extension:
+
+```sh
+node bin/lookout.mjs restore --yes
+```
+
+This affects all projects using the server. It removes only marked Lookout
+entries. Existing permissions, policies, credentials, and plugin entries remain.
+
+## Browse the catalog
+
+Run `/lookout`, or choose **Open Lookout** in the command palette.
+Use `/lookout skill` to start with one category. Category names are `agent`,
+`skill`, `plugin`, `command`, `provider`, and `model`.
+
+The catalog uses OpenCode's native searchable dialogs:
+
+| Action | Control |
+| --- | --- |
+| Search names, IDs, descriptions, and model details | Type in the search field |
+| Change category | Ctrl+F |
+| Filter by state | Ctrl+S |
+| Refresh the inventory | Ctrl+R |
+| Inspect an item or change it | Enter |
+| Return or close | Escape |
+
+Selecting an item opens its action menu. **Show details** opens a read-only
+inspector; Escape closes it back to the prompt. Run `/lookout` again to
+browse another item.
+
+Sidebar headings expand or collapse on click. Each expanded category shows up to
+three entries. Select an item and choose **Pin to sidebar** to choose which entries
+appear. Pins and collapsed sections are terminal presentation preferences; they
+do not enable or disable resources. Keyboard-only users can access every resource
+and action through `/lookout`, even when the terminal hides the sidebar.
+
+Status dots use the native sidebar's semantic theme colors: green for available
+or active entries, yellow for pending, stale, unknown, or still-listed restrictions,
+grey for disabled or inactive entries, and red for failures. The selected agent
+also has an arrow. Green reflects catalog availability, not verified provider
+authentication, quota, or successful execution. Open an item's details for its
+text status.
+
+Plugin rows include a description from their own files. For local plugin
+directories, Lookout reads the `description` string in that directory's
+`package.json`. For single-file plugins, it reads a leading JSDoc tag:
+
+```js
+/** @description Explain what this plugin does. */
+export default { id: "example.plugin", setup() {} };
+```
+
+If metadata is missing, unreadable, or unsupported, the row says
+`missing description`. Lookout does not execute plugin code, search parent
+packages, fetch registry metadata, or keep a hardcoded description list. Packaged
+or built-in plugins whose catalog entry has no local source path use the fallback.
+Descriptions are truncated in the sidebar; open **Show details** to read more.
+
+## What the controls mean
+
+Resource changes require a preview and **Apply Globally** confirmation. They affect
+every project using that server, not just the current conversation. Wait for other
+work to finish before changing resources it may use.
+
+| Resource | Supported control |
+| --- | --- |
+| Skills from configured local sources | Add an exact `skill.use` denial |
+| Local plugins inside your OpenCode configuration directory | Add an exact `-plugin-id` entry |
+| Agents | Inspect; use `/agents` to select |
+| Commands, providers, models | Inspect; use native OpenCode or Console controls |
+| Built-in, managed, unknown-source plugins | Read-only |
+| Lookout itself | Use the external `unload` command |
+
+**Enable** removes this extension's denial. It never adds an `allow`, removes an
+external restriction, or overrides managed policy. A missing resource stays in
+the catalog as a disabled row when Lookout owns its restriction, so you can
+restore it after a reload or restart.
+
+Lookout MCP restrictions are preserved, not silently removed when the inventory
+is hidden. Use the external `restore --yes` command to remove all Lookout
+restrictions, including MCP entries. The MCP RPC contract remains available for
+recovery; it is not exposed in the browser.
+
+**Restricted; still listed** means the config entry exists but the live catalog
+still includes the resource. Do not interpret that state as successful blocking.
+Higher-priority policy, reload timing, or plugin ordering may explain the result.
+Refresh and use the native controls to verify access. Disabling a skill does not
+remove instructions already loaded into an existing conversation.
+
+## Troubleshoot
+
+1. Run `node bin/lookout.mjs status` to inspect the load entry and owned
+   restriction count. No credentials are needed.
+2. Run `node bin/lookout.mjs unload` to remove both extension parts from
+   configuration. The package lives outside automatic plugin discovery.
+3. Use `/reload`. If only the terminal is unusable, open a terminal without its UI:
+
+   ```sh
+    OPENCODE_CLI_CONFIG_CONTENT='{"plugins":["*","-opencode-lookout"]}' opencode
+   ```
+
+   This suppresses only the TUI part for that process. Use `unload` for the server
+   part. It does not bypass any policy or remove resource restrictions.
+4. Fix the failure, run `make check`, and use `load` to re-enable the extension.
+
+If an apply request loses its response during configuration reload, refresh before
+retrying: the write might already have succeeded. If a `.lookout-lock` file remains
+after a crash, first ensure no Lookout command is running. Inspect the lock
+beside your global config, then remove that lock manually and retry. Never delete
+the global configuration to clear a lock.
+
+Do not edit text inside `lookout:begin` / `lookout:end` ownership markers. The controller
+rejects modified blocks rather than risk deleting your edits. Unload still works
+without calling the server. Preserve the file and repair the marked block manually
+if normal restore cannot parse it.
+
+## Development
+
+```sh
+npm ci --ignore-scripts
+make check
+npm run test:integration
+npm run test:tui
+LOOKOUT_TUI=1 LOOKOUT_NARROW=1 LOOKOUT_THEME=tokyonight npm run test:integration
+```
+
+The integration checks require the `opencode` executable. Terminal checks also
+require `/usr/bin/expect`. They use a temporary HOME and deny provider and tool
+use. Set `LOOKOUT_KEEP_FIXTURE=1` to retain a failed fixture for local inspection; do not
+share its credential files or raw terminal transcript.
+
+See [Architecture](docs/ARCHITECTURE.md) for module boundaries and configuration
+ownership, [Threat model](docs/THREAT_MODEL.md) for safety limits, and
+[Validation](docs/VALIDATION.md) for evidence and remaining manual checks.
+
+## Project information
+
+- [Contributing](CONTRIBUTING.md): setup, tests, and review expectations.
+- [Security](SECURITY.md): supported versions and private vulnerability reports.
+- [Support](SUPPORT.md): troubleshooting and useful bug reports.
+- [Code of conduct](CODE_OF_CONDUCT.md) and [governance](GOVERNANCE.md).
+- [Changelog](CHANGELOG.md) and [MIT license](LICENSE).
+- [Repository metadata and release policy](docs/RELEASING.md).

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security policy
+
+Lookout runs with the filesystem authority of your OpenCode process. Its controls
+edit global configuration and can affect other sessions. It is not a sandbox.
+Read the [threat model](docs/THREAT_MODEL.md) before enabling resource controls.
+
+## Supported versions
+
+Security fixes target the current `main` branch. The initial package version is
+0.1.0, targeting OpenCode 2.2.5. The release matrix requires read-only behavior on
+2.2.1–2.2.2 and full controls on supported V2 versions from 2.2.3 onward. Consult
+the exact release's test evidence; the API version floor is not a blanket claim
+that every future CLI is compatible. There are no maintained older release
+branches or guaranteed response times.
+
+## Report a vulnerability privately
+
+Use [GitHub's private vulnerability report form](https://github.com/sodejm/opencode-lookout/security/advisories/new).
+Include affected revisions, impact, and a minimal reproduction with synthetic
+data. Do not open a public issue containing exploit details, credentials, global
+configuration, or retained test transcripts. If the private form is unavailable,
+open an issue asking for a private reporting channel without technical details.
+
+If a credential was exposed, revoke or rotate it through its provider. Removing
+it from an issue or commit is not enough. Do not send the credential to maintainers.
+
+The maintainer will assess the report, coordinate a fix and disclosure, and credit
+reporters who want attribution. Automated checks are not security certification.
+
+## Safe recovery
+
+From the installed checkout, run `node bin/lookout.mjs unload`. This works
+without OpenCode and preserves resource restrictions. Use `restore --yes` only
+when you intend to remove all restrictions owned by this extension. Never delete
+the global configuration to recover. See the [recovery guide](README.md#troubleshoot).

package/SUPPORT.md

@@ -0,0 +1,20 @@
+# Support
+
+For usage questions, open a [GitHub issue](https://github.com/sodejm/opencode-lookout/issues).
+For vulnerabilities, follow [Security](SECURITY.md) instead. This is a volunteer
+project; support has no service-level or response-time guarantee.
+
+Before reporting a problem:
+
+1. Read the [troubleshooting steps](README.md#troubleshoot).
+2. Record your OpenCode and Node.js versions, operating system, terminal, theme,
+   and approximate terminal dimensions.
+3. Run `node bin/lookout.mjs status` from the checkout. It reports disk
+   configuration, not proof that the server or UI loaded successfully.
+4. Describe expected and actual behavior, steps to reproduce, and whether external
+   unload restores normal behavior. Include the Lookout commit ID if available.
+
+Share only sanitized excerpts. Remove tokens, personal paths, prompts, session
+identifiers, MCP commands, and private server addresses. Do not attach your full
+global config, logs, or retained integration fixtures. Reproduce with synthetic
+data when possible.

package/bin/lookout.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/** Offline lifecycle controls. Never require a running server, TUI, or credentials. */
+import { access, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ID, lifecycle, owned, change, parseConfig } from "../src/config.mjs";
+import { atomicUpdate, readConfig } from "../src/controller.mjs";
+
+/** Resolve only the user's global config; fail rather than choose between two files. */
+export async function configFile() {
+  const directory = join(
+    process.env.XDG_CONFIG_HOME || join(homedir(), ".config"),
+    "opencode",
+  );
+  const files = [];
+  for (const name of ["opencode.jsonc", "opencode.json"]) {
+    const file = join(directory, name);
+    if (
+      await access(file).then(
+        () => true,
+        () => false,
+      )
+    )
+      files.push(file);
+  }
+  if (files.length !== 1)
+    throw new Error(
+      "Expected exactly one global opencode.json or opencode.jsonc. No files changed.",
+    );
+  return files[0];
+}
+
+/**
+ * load/unload changes only the marked package entry. restore removes all owned
+ * resource restrictions and requires --yes because it can restore tool access.
+ * Status describes disk configuration, not server or TUI readiness.
+ * @param {string[]} args CLI arguments, excluding the executable and script path.
+ * @returns {Promise<void>} Resolves after the requested operation and status output.
+ */
+export async function main(args = process.argv.slice(2)) {
+  const [command = "status", confirmation] = args;
+  if (
+    !["load", "unload", "status", "restore"].includes(command) ||
+    args.length > 2 ||
+    (confirmation !== undefined &&
+      (command !== "restore" || confirmation !== "--yes"))
+  )
+    throw new Error(
+      "Usage: node bin/lookout.mjs [load|unload|status|restore --yes]",
+    );
+  if (command === "restore" && confirmation !== "--yes")
+    throw new Error(
+      "Restore removes every Lookout restriction globally. Repeat with restore --yes to confirm.",
+    );
+  const file = await configFile();
+  const packagePath = dirname(dirname(fileURLToPath(import.meta.url)));
+  if (command === "load" || command === "unload") {
+    await atomicUpdate(file, null, (text) =>
+      lifecycle(text, packagePath, command === "load"),
+    );
+    console.log(
+      `Lookout ${command === "load" ? "load" : "unload"} configured. OpenCode watches this file; use /reload if needed.`,
+    );
+    if (command === "unload")
+      console.log(
+        "Resource restrictions were preserved. Use restore --yes separately to remove them.",
+      );
+  } else if (command === "restore") {
+    await atomicUpdate(file, null, (text) =>
+      owned(text).reduce((next, r) => change(next, r.kind, r.id, true), text),
+    );
+    console.log(
+      "Removed Lookout restrictions only. Other policies and disabled settings remain unchanged.",
+    );
+  }
+  const { text } = await readConfig(file);
+  const value = parseConfig(text).plugins;
+  const plugins = Array.isArray(value) ? value : [];
+  console.log(
+    `Package entry: ${plugins.includes(packagePath) ? "present" : plugins.includes("-" + ID) ? "disabled" : "not configured"}`,
+  );
+  console.log(`Owned restrictions: ${owned(text).length}`);
+}
+if (
+  process.argv[1] &&
+  // npm invokes the executable through node_modules/.bin (a symlink on Unix).
+  (await realpath(process.argv[1]).catch(() => "")) ===
+    fileURLToPath(import.meta.url)
+) {
+  main().catch((error) => {
+    console.error(
+      error?.code
+        ? "Cannot access configuration safely. Check permissions; no credentials are needed."
+        : error.message,
+    );
+    process.exitCode = 1;
+  });
+}