@n8r/surface 0.1.0-experimental.2 → 0.1.0-experimental.5

package/docs/n8r-surface/versioning.md

@@ -1,11 +1,16 @@
 # Package version and release identity
 
-The [approved decision in issue #27](https://github.com/injectionator/n8r-surface/issues/27#issuecomment-6661015093)
-applies to both `@n8r/surface` and `n8r-surface`. Their authoritative version is
-`package.json`; the lockfile must agree. Both packages come from one build of one
-commit. The installed command reads its own manifest for `--version`, regardless
-of the working directory. Package versions do not version the AI Surface Model,
-Researcher skill, or individual saved Surface revisions.
+The distribution plan is **`@n8r/surface` only**. Its authoritative version is
+`package.json`; the lockfile must agree, and the installed command reads its own
+manifest for `--version`. Package versions do not version the AI Surface Model,
+Researcher skill or individual saved Surface revisions.
+
+The maintainer removed unscoped publication and name reservation from the plan
+on 5 November 2026. The first verified release is
+[`@n8r/surface@0.1.0-experimental.2`](npm-release.md#verified-scoped-release).
+Historical dual archives remain evidence, not a second supported package or a
+future publication commitment. Current tooling prepares only the scoped package; preparation does not authorize
+a release.
 
 ## Compatibility and version changes
 
@@ -31,15 +36,15 @@ Use `npm version VERSION --no-git-tag-version` for an approved version change,
 then review both manifests in the issue's PR. `npm run check:version` rejects
 invalid versions and drift in either lockfile version. `npm test` and candidate
 packing run that check. A version bump needs no source-code edit for CLI output.
-The maintainer confirmed `0.1.0-experimental.2` and authorized publication on
-5 November 2026. Review/merge and required account actions remain separate. See
-the [first-release procedure](npm-release.md).
+The maintainer authorized the next release on 14 November 2026. The current
+release is `0.1.0-experimental.5`; required account actions remain separate. See
+the [release procedure](npm-release.md#experimental5-release).
 
 npm distribution tags are movable pointers, unlike permanent Git release tags:
 
-- Experimental prereleases use explicit `experimental` on both packages.
+- Experimental prereleases use explicit `experimental` on the scoped package.
 - Release candidates use explicit `next`; they must not update `latest`.
-- Stable releases may use `latest` only after both exact-version routes pass
+- Stable releases may use `latest` only after the scoped exact-version route passes
   verification and promotion is authorized. Publish initially under `next` to
   permit independent readback before promotion.
 
@@ -58,19 +63,14 @@ that do not report `immutable: true`. No repository settings are changed by
 these local tools. Review/approval of the selected commit is a maintainer
 prerequisite; the verifier checks identity, not the adequacy of code review.
 
-Retain `candidates.json` and both exact tarballs from the approved build. Each
-report entry has a `releaseAsset` name, respectively
-`n8r-surface-VERSION-scoped.tgz` and `n8r-surface-VERSION-unscoped.tgz`. Copy the
-bytes under those distinct names when uploading release assets, since npm gives
-both original tarballs the same basename. Upload the report too, and retain the
-build environment, test evidence, release notes and per-package registry results.
-SHA-256 identifies bytes; it does not authenticate the builder.
+Retain the approved scoped archive, its digest report, build environment, test
+evidence, release notes and registry readback. SHA-256 identifies bytes; it does
+not authenticate the builder. Do not rebuild or alter a published version.
 
-The source packer requires `private: true`. The explicit `--publishable` option
-creates fresh publishable archives at the approved first version; ordinary
-candidates stay private. Use a fresh reviewed commit and build. Do not strip the guard from an old tarball
-and keep its old hash or claim it was built from an unchanged commit. The current
-verifier accepts private artifacts only for draft metadata rehearsals.
+The packer produces one scoped archive. Preserve the historical reports and both
+archives for verification of `.1` and `.2`; their version-specific verification
+still checks both. Source and default candidates remain private. Never strip a
+guard from an old tarball and retain its old digest or source claim.
 
 ## Read-only verification commands
 
@@ -84,7 +84,7 @@ npm run check:release -- /path/to/candidates
 
 The second command reads GitHub's release API and resolves the remote tag. It
 checks the source and lockfile versions, clean HEAD, report revision/dirty flag,
-local and remote tag targets, release target SHA and prerelease flag, both archive
+local and remote tag targets, release target SHA and prerelease flag, required archive
 manifests and hashes, and matching uploaded asset names/digests. It fails closed
 on missing data or API errors. A passing JSON result includes the version,
 revision, tag, draft status, `evidence: "GitHub API readback"`, and explicit
@@ -107,42 +107,31 @@ performs explicitly selected publication; registry permissions remain external.
 
 ## Authentication, provenance and incomplete releases
 
-Before any first publication, establish the npm account, package ownership and
-`n8r` organization/team rights for both names. The official
-[scoped publication guide](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/)
-documents public access and direct-publication authentication requirements.
-Its staged first-publication path creates a public placeholder; staging is not
-a read-only readiness check. The maintainer approved this staged route for the
-first release after npm offered stage-only tokens; submit the actual retained
-artifacts, not an empty reservation package. The [procedure](npm-release.md)
-requires maintainer 2FA approval of both real versions.
+Future publication requires an authorized npm identity with write access to
+`@n8r/surface`. Unscoped ownership, reservation and defensive publication are
+out of scope. The first release used a stage-only token, followed by maintainer
+2FA approval; [the release record](npm-release.md#verified-scoped-release)
+contains the observed results.
 
 Prefer [trusted publishing](https://docs.npmjs.com/trusted-publishers/) from the
-public repository using GitHub-hosted runners. Configure each package separately
-for the exact workflow and environment. npm documents Node 22.14+ and npm 11.5.1+
-for trusted publishing; its dist-tag permission is separate and requires newer
-npm (11.21.0+ in the 11 series or 12.2.0+ in the 12 series). A newly configured
-publisher must complete a successful publish within two days or be recreated.
-These are prerequisites to verify during release preparation, not settings this
-increment changes. References checked 5 November 2026.
-
-For each exact installed registry version, run `npm audit signatures` and inspect
-its [provenance](https://docs.npmjs.com/generating-provenance-statements/). Require
-evidence for the package itself, not merely an attested dependency. Compare the
-attestation's source commit/repository and artifact digest with the approved
-release. Also compare registry tarball bytes with the retained SHA-256 and record
-registry `dist.integrity`. A repository URL or locally generated hash is not
-registry provenance. Repeat the [isolated consumer checks](npm-distribution.md#human-verification)
-and documented npm-exec routes for both names.
-
-If one package publishes and the other fails, the release is **incomplete**.
-Retain the exact build and draft GitHub Release. Inspect the existing published
-bytes and evidence, then retry only the missing package using the retained
-artifact after resolving the failure. Never rebuild or overwrite the published
-version. A mismatch requires a new approved version for both names. Promote both
-npm dist-tags and finalize the immutable GitHub Release only after both routes
-pass. If tag promotion partially fails, record that too and repair only the
-missing pointer update; it does not require republishing package bytes.
+public repository on GitHub-hosted runners for future scoped releases. Configure
+only `@n8r/surface` for the reviewed workflow/environment. This has not yet been
+exercised. Recheck npm's current requirements before setup; a newly configured
+publisher must complete a successful publication within two days or be recreated.
+Keep credentials outside tracked files.
+
+For the exact scoped registry version, verify registry signatures and the
+package's own provenance, source repository/commit, workflow identity and subject
+digest. Compare downloaded bytes with the retained SHA-256 and registry integrity.
+Exercise the documented isolated installation and npm-exec route. An attested
+dependency or matching repository text alone is insufficient.
+
+If submission or verification fails, keep the release incomplete and retain its
+exact archives. Check whether the version already exists before retrying; verify
+existing bytes instead of overwriting or silently rebuilding them. A mismatch
+requires a new approved version. Finalize the immutable GitHub Release only after
+the scoped package passes acceptance. Promote `latest` only after a separate
+promotion decision; no unscoped publication is required.
 
 ## Human check for this increment
 
@@ -152,26 +141,26 @@ No npm credentials, real Git tag, GitHub Release or global-install change is nee
 Keep the current terminal with `candidate_run` set by that guide.
 
 - [ ] From the checkout root run `npm run check:version`. Expect
-  `Version consistent: 0.1.0-experimental.2`, exit 0. Inspect `package.json` and
+  `Version consistent: 0.1.0-experimental.5`, exit 0. Inspect `package.json` and
   both root version fields in `package-lock.json`; they must match.
 - [ ] Follow the [candidate install steps](npm-distribution.md#human-verification)
-  for both names. In each consumer directory run:
+  for the scoped package. In its consumer directory run:
 
   ```sh
   node -p 'require("./node_modules/@n8r/surface/package.json").version'
   ./node_modules/.bin/n8r-surface --version
   ```
 
-  For the alternative use `./node_modules/n8r-surface/package.json`. Expect
-  `0.1.0-experimental.2` and `n8r-surface 0.1.0-experimental.2`, both exit 0.
-- [ ] Inspect `candidates.json`: both entries have distinct `releaseAsset` names,
-  the same report version/revision, and hashes matching the retained tarballs.
+  Expect
+  `0.1.0-experimental.5` and `n8r-surface 0.1.0-experimental.5`, both exit 0.
+- [ ] Inspect `candidates.json`: one scoped entry has its `releaseAsset` name,
+  the report version/revision, and a hash matching the retained tarball.
   A clean-commit rehearsal must say `dirty: false`.
 - [ ] Read the compatibility table and release/recovery procedure above. Expect
-  one permanent Git tag and exact commit for both package names; `experimental`
+  one permanent Git tag and exact commit for the scoped package; `experimental`
   and `next` do not silently promote `latest`.
 - [ ] Report **Pass / Fail / Blocked**, Node/npm versions, report revision and
-  both CLI outputs. Version drift or missing artifacts is Fail. Missing real
+  the scoped CLI output. Version drift or missing artifacts is Fail. Missing real
   release/authentication is Blocked for live release verification, not a reason
   to create a tag or publish. Clean up only the temporary consumer directory
   created by the distribution procedure after retaining needed evidence.

package/docs/n8r-surface/workspace-human-check.md

@@ -0,0 +1,101 @@
+# Check workspace setup and continuation
+
+Use [the canonical scenarios](../../tests/acceptance/skill-workspace.feature).
+This is a PM walkthrough through the installed skill, not a developer executing
+the helper and calling it product acceptance. Keep this guide and expected answers
+out of the product chat. Current results are in [verification](workspace-verification.md).
+
+## Maintainer preparation
+
+- Identify the candidate commit, plugin version and every installed file digest.
+  Follow [candidate installation](workspace-installation.md). Verify the actual
+  loaded skill path from tool receipts; a version announcement alone is insufficient.
+- Use a local Codex desktop chat with ordinary inference sign-in, persistent
+  filesystem access and Node.js 22, 24 or 26. Record actual app/build, selected
+  model and CLI version. Unsupported/cloud-only hosts are blocked, not passed.
+- Prepare disposable folders outside source repositories. Keep evidence outside
+  product inputs. Create one empty folder each for create and alternative choice;
+  leave a missing destination absent. For each adoption case create a folder with
+  `user-note.md` containing `Synthetic user note: preserve this text.`
+- Prepare independent refusal folders: malformed `.n8r/workspace.json` containing
+  `{`; conflicting `.n8r` as a plain text file; unsupported identity JSON with
+  `format: n8r.workspace/2`. These are inputs, not seeded successful workspaces.
+- Record the owned fixture inventory, all initial file bytes/hashes and directory
+  entries. Record global/project instructions, enabled tools, memory/history and
+  filesystem access. Verify the selected folder is actually available. Do not
+  attribute host-created `.git` to the skill. Do not call a nonempty folder empty.
+- Start a separate fresh product chat. Supply only the installed skill, selected
+  folder and ordinary user prompt. Never include this implementation chat,
+  expected outputs or hidden repair hints. Record isolation limits; a fresh chat
+  alone is not proof that history/filesystem access is excluded.
+
+## PM tasks
+
+- [ ] Open the prepared empty folder in a fresh local chat. Select the installed
+  **n8r-surface Researcher** and send:
+
+  > Help me set up an n8r workspace here for investigating LibreChat.
+  > Set it up only; do not start researching yet.
+
+  Expect a clear saved location and useful next step, without beginning research.
+  It should distinguish creation from app attachment and require no source or
+  credentials. Open the folder with hidden files visible: only
+  `.n8r/workspace.json` should be new. Open it and record its ID and format.
+- [ ] Add `user-note.md` containing `Synthetic user note: preserve this text.`
+  Ask: “Set up this n8r workspace here again.” Expect recognition without a new
+  identity, rewrite or repeated permission question. The note remains unchanged.
+- [ ] In a new chat, select the same folder and installed skill, then send:
+
+  > Is this n8r workspace ready, and what can I do next?
+
+  Expect the same saved identity/format, useful continuation from saved purpose,
+  no claim of completed LibreChat research and no writes or research.
+- [ ] Move the disposable folder using the file manager. Open it in another fresh
+  chat and repeat the readiness question. Expect the same identity at the new
+  location. Do not move a borrowed/user-owned workspace for this test.
+- [ ] Repeat setup with the absent destination, stating its location in the prompt.
+  Expect the same minimal creation without a redundant permission question.
+- [ ] Use each adoption fixture separately. Ask setup; expect a choice before any
+  write. Answer “Initialize here” in one run; choose the prepared alternative
+  empty folder in the other. Expect the chosen destination initialized and every
+  original user file preserved.
+- [ ] Ask setup in each refusal fixture. Expect a specific explanation and next
+  action, no success claim, repair, migration or file changes.
+
+Answer only genuine questions using the scenario facts. Stop at technical rescue,
+10 exchanges or 15 minutes; retain the failed/incomplete trial. Do not silently
+fix files, change the expectation or retry until a pass.
+
+## Independent evidence and report
+
+The maintainer compares complete before/after file inventories and hashes, then
+reads saved JSON independently of the helper. Verify UUID v4, exact format,
+nonempty name, optional purpose, stable ID and unchanged note bytes. Record tool
+exit statuses (helper success 0, choice/uninitialized 3, refusal/error 2), actual
+messages/tool receipts, timestamps and unrelated/global-state checks. Helper
+calls in automated tests are supporting evidence, not this chat journey.
+
+Report each scenario's **Outcome: Pass / Fail / Blocked**, with file/tool evidence.
+Separately score **Experience: Pass / Fail / Blocked** for each:
+
+| Criterion | Evidence to return |
+| --- | --- |
+| Orientation | Turn showing location, completion state and useful next action. |
+| Necessary questions | Each question and why its information was missing. |
+| User effort | Any request to choose a schema/structure or perform technical rescue. |
+| Honest boundaries | Attachment, access and failure statements versus actual tools/state. |
+| Scope | Whether setup/readiness ended without research. |
+
+False completion, unauthorized effects or lost data fail regardless of conversation
+quality. An expected refusal can pass; an unavailable host is blocked. Record
+invalid environment separately. Wording, paths, names, UUIDs and timings may vary;
+identity changes, unexpected writes or invented research are failures. Retain
+sanitized PM judgments and private evidence references, including failed trials.
+
+## Cleanup
+
+Retain transcripts, hashes and verdicts before cleanup. Remove only the exact
+inventoried task-owned fixture and isolated-installation roots when authorized;
+verify removal. Never delete the normal installation, borrowed folders or research.
+Record deliberate retention and leftovers. Installation, rehearsal, acceptance,
+merge and release are separate states.

package/docs/n8r-surface/workspace-installation.md

@@ -0,0 +1,68 @@
+# Install an identified workspace candidate
+
+Plugin `0.1.9` belongs to issue #41 on `feat/41-skill-workspace`. Pin the reviewed
+commit from the draft PR; a moving branch alone is not repeatable provenance.
+This procedure exercises installation without replacing the normal installation.
+It does not establish desktop invocation or PM acceptance.
+
+## Isolated maintainer installation
+
+Prerequisites: Git, Codex CLI 0.166.0, Python 3 and network access for a Git
+marketplace. From the n8r-surface checkout at the reviewed commit:
+
+```sh
+n8r_candidate_revision=$(git rev-parse HEAD)
+n8r_candidate_root=$(mktemp -d)
+mkdir "$n8r_candidate_root/codex"
+env CODEX_HOME="$n8r_candidate_root/codex" codex plugin marketplace add injectionator/n8r-surface --ref "$n8r_candidate_revision" --json
+env CODEX_HOME="$n8r_candidate_root/codex" codex plugin add n8r-surface@n8r-surface --json
+env CODEX_HOME="$n8r_candidate_root/codex" codex plugin list --marketplace n8r-surface --json
+```
+
+Expected: exit 0; exactly one installed/enabled `n8r-surface@n8r-surface` at
+`0.1.9` in the isolated home. Keep the root and revision in a private run inventory.
+The environment override is scoped to each process, not exported into the normal
+shell. No inference credentials are copied. These install operations need no model
+sign-in. Do not claim that this changes the desktop app's active installation.
+
+Use `git archive` of the exact commit to compare every plugin-relative file and
+SHA-256 digest to the listed installed path. Verify both manifests, SKILL.md,
+references and `scripts/workspace.mjs`; preserve a complete digest inventory.
+Run the installed helper only in a separate technical fixture to check packaging.
+Do not use that helper-created fixture as the PM's new-user input.
+
+For an offline/local marketplace rehearsal, archive the exact commit's
+`.agents/plugins/marketplace.json` and `plugins/n8r-surface` into a task-owned
+source directory and register that directory instead. This uses the repository
+marketplace layout without editing its name or installing a second skill.
+Record that local delivery route distinctly from Git fetch verification.
+
+## Upgrade rehearsal
+
+Use another isolated home and install baseline commit
+`3effc41bf7e8466651722b7b4c64035f862b1901` (plugin `0.1.8`) first. Independently
+snapshot a synthetic user workspace outside the installation. Remove only that
+isolated marketplace registration, register the exact candidate revision, and
+run `plugin add` again. A pinned marketplace does not float to a new commit.
+Expect `0.1.9`, byte equality with the candidate, and an unchanged user workspace.
+This tests replacement of the installed snapshot; fresh-chat skill use remains
+[a separate PM task](workspace-human-check.md).
+
+## Desktop product rehearsal
+
+The PM must choose an explicit installation route for the actual desktop session.
+An isolated CLI installation is not automatically visible there. Record the normal
+registration first. If the PM authorizes replacing it for the trial, use the pinned
+candidate registration/add sequence, verify installed bytes, refresh the app if
+needed and start fresh product chats. Keep the original source/ref available for
+restoration. Never remove/repoint the normal registration silently.
+
+Alternatively use a separately verified host configuration that loads the isolated
+installation. Verify this from actual tool receipts before testing. Do not assume
+an environment override affects an already-running desktop process.
+
+[Official plugin packaging guidance](https://developers.openai.com/plugins/build/plugins)
+describes the repository marketplace and bundled resources. The commands above
+must also be checked against the installed CLI's help and actual results.
+Neither repository marketplace installation nor a ZIP is a public Plugins
+Directory listing, npm release or authorization to merge.