docs(release): prepare documented release candidate

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project are documented here.
 
 ## [Unreleased]
 
+### Documentation
+- Document release-candidate tarball verification and record the pre-release
+  installer security review and its operational limitations.
+
 ### Fixed
 - Register the project-local plugin directory instead of prompting OpenCode to
   download the unpublished package from npm; enable the namespaced tool through

README.md

@@ -50,6 +50,59 @@ Modified managed files are preserved and reported. The installer does not yet
 remove the npm dependency from the consuming project's `package.json`; remove
 that dependency separately if desired.
 
+To update, install the newer checkout or tarball into the consuming project,
+then rerun the installer. It updates files that still match their recorded
+hashes and refuses to overwrite a locally modified current file:
+
+```sh
+npm install --save-dev /path/to/new-opencode-toolkit.tgz
+npx opencode-toolkit install .
+```
+
+## Verify a package tarball
+
+For a release candidate, build the package and create a tarball from the checkout:
+
+```sh
+npm pack
+```
+
+This creates `sargatxet-opencode-toolkit-0.1.0.tgz` for the current provisional
+package identity and version. In a disposable project, install that tarball
+rather than linking the checkout:
+
+```sh
+npm install --save-dev /path/to/sargatxet-opencode-toolkit-0.1.0.tgz
+npx opencode-toolkit install .
+npx opencode-toolkit install .
+```
+
+The second install should make no content changes. Check that the expected
+`toolkit-*` agents and skills are present under `.opencode/`, and that the
+project config contains the local package plugin path. To verify removal, first
+edit one installed toolkit file, then run:
+
+```sh
+npx opencode-toolkit uninstall .
+```
+
+The edited file should be reported as preserved; unmodified managed files and
+the toolkit plugin entry should be removed. These install/uninstall checks need
+no model credentials. Plugin activation and tool execution were separately
+smoke-tested with OpenCode 2.0.24 and a local mock OpenAI-compatible endpoint.
+Provider-backed agent delegation and skill behavior remain unverified.
+
+## Safety boundaries
+
+The installer rejects unmanaged-file collisions, symlinked install paths, and
+managed files changed since installation. Its ownership manifest is local
+bookkeeping, not a signed security boundary. Path checks do not protect against
+another process changing the project tree concurrently; use it on a project
+directory whose filesystem is trusted. Uninstall removes files incrementally,
+so resolve any reported I/O error and rerun it rather than deleting the manifest
+manually. See [`docs/SECURITY-REVIEW.md`](docs/SECURITY-REVIEW.md) for the review
+scope and limitations.
+
 After installation, restart or reload OpenCode and select the installed
 `toolkit-*` skills or subagents as needed. The plugin exposes its namespaced
 tool through Code Mode. Configure and authenticate your provider normally in
@@ -65,21 +118,17 @@ npm run test:coverage
 npm pack --dry-run
 ```
 
-The package is tested against OpenCode `2.0.24`. The unit and installer tests
+The package is tested against OpenCode `2.0.24` and Node.js `20+`. The unit and
-are deterministic and do not call an LLM. Plugin activation and tool execution
+installer tests are deterministic and do not call an LLM. Plugin activation and
-were smoke-tested with a local mock OpenAI-compatible endpoint; provider-backed
+tool execution were smoke-tested with a local mock OpenAI-compatible endpoint;
-agent and skill workflows are not yet complete. See [`FIXME.md`](FIXME.md) and
+provider-backed agent delegation and skill behavior remain unverified.
-[`TODO.md`](TODO.md).
 
-## Project documentation
+## Provenance and security
 
-- [`AGENTS.md`](AGENTS.md): verified development commands and conventions.
-- [`docs/IMPLEMENTATION-PLAN.md`](docs/IMPLEMENTATION-PLAN.md): accepted plan,
-  phases, scope, and acceptance criteria.
 - [`docs/PROVENANCE.md`](docs/PROVENANCE.md): ECC source revision, attribution,
   adaptations, and content hashes.
-- [`CHANGELOG.md`](CHANGELOG.md): user-visible changes.
+- [`docs/SECURITY-REVIEW.md`](docs/SECURITY-REVIEW.md): review scope, result,
-- [`TODO.md`](TODO.md) and [`FIXME.md`](FIXME.md): remaining work and known gaps.
+  and operational limitations.
 
 ## License
 

TODO.md

@@ -21,6 +21,10 @@
   array merge and precedence behavior.
 - [x] Install the package tarball into a clean project outside this repository;
   verify CLI idempotency and native agent discovery.
+- [x] Document how to install and verify a release-candidate tarball without
+  credentials, including idempotency and conservative uninstall checks.
+- [x] Perform and record a pre-release manual security review of installer paths,
+  file ownership, configuration edits, and failure limitations.
 - [ ] Add provider-backed verification after confirming credentials and model
   usage budget with the user.
 - [ ] Confirm repository/package names and decide whether to publish.

docs/IMPLEMENTATION-PLAN.md

@@ -139,13 +139,22 @@ provider-backed agent delegation and skill behavior remain unverified.
 runtime; config collisions are handled or reported before writes; the V2 plugin
 and its custom tool are confirmed active.
 
-### Phase 5 — Document and release (documentation baseline complete)
+### Phase 5 — Document and release (release candidate prepared; publication pending)
 
 - Document scope, installation, update/uninstall, compatibility, provenance,
   and known limitations.
 - Run deterministic checks and security review before release.
 - Confirm package/repository names and get explicit approval before publishing.
 
+**Progress:** README now documents checkout installation, tarball verification,
+update/uninstall behavior, compatibility, and credential-free checks. A manual
+pre-release review of installer paths, ownership, JSONC edits, symlinks, and
+failure behavior found no release blocker for trusted project-local use; its
+filesystem and provider-backed limitations are recorded in
+[`SECURITY-REVIEW.md`](SECURITY-REVIEW.md). Typecheck, all 16 tests, coverage
+(87.4% lines), and package dry-run passed. Publication remains blocked on
+explicit confirmation of the package/repository identity and destination.
+
 **Acceptance:** another user can install from documented instructions and
 verify the deterministic behavior without credentials.
 

docs/SECURITY-REVIEW.md

@@ -0,0 +1,44 @@
+# Pre-release security review
+
+## Scope
+
+Manual source review of the project installer, JSONC configuration edits, CLI,
+and packaged content before the first release. The review focused on path
+containment, symlink handling, file ownership, preserving user changes, and
+partial failures. This is not an independent audit, a guarantee against local
+filesystem attackers, or a review of provider/model behavior.
+
+## Result
+
+No release-blocking issue was identified for the documented project-local use
+on a trusted filesystem. The installer resolves the project root, restricts
+manifest paths to toolkit asset locations, rejects symlinked install paths and
+non-regular files, refuses unmanaged collisions, and verifies hashes before
+replacing or removing managed content. Configuration changes use JSONC edits
+and preserve unrelated entries. Deterministic tests cover collisions, modified
+files, symlinked install directories, and a tampered manifest.
+
+## Limitations and operational guidance
+
+- The installer does not defend against a concurrent process replacing a path
+  after it has been checked (a filesystem time-of-check/time-of-use race). Run it
+  only where another actor cannot concurrently manipulate the project tree.
+- The ownership manifest is ordinary project-local JSON, not an authenticated
+  record. It protects against accidental overwrite/removal, not a malicious
+  project owner who can edit both the manifest and files.
+- Uninstall removes managed files incrementally. If an I/O failure interrupts
+  it, the manifest is retained for recovery in normal mid-operation failures;
+  resolve the filesystem problem and rerun uninstall. Transactional rollback
+  for uninstall remains future work.
+- Provider-backed agent delegation and skill invocation have not been reviewed
+  or verified. The runtime smoke test only covered plugin activation and the
+  read-only status tool with a local mock provider.
+
+## Checks run
+
+- `npm run typecheck` — passed.
+- `npm test` — passed, 16 tests.
+- `npm run test:coverage` — passed; 87.4% lines, 95.23% functions, and 81.86%
+  branches.
+- `npm pack --dry-run` — passed; included runtime files, selected content,
+  licenses, notice, and README.

package.json

@@ -29,7 +29,9 @@
     "LICENSE",
     "LICENSE-ECC",
     "NOTICE.md",
-    "README.md"
+    "README.md",
+    "docs/PROVENANCE.md",
+    "docs/SECURITY-REVIEW.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",