@n8r/surface 0.0.0-stage → 0.1.0-experimental.5

package/docs/n8r-surface/versioning.md

@@ -0,0 +1,172 @@
+# Package version and release identity
+
+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
+
+Follow [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html) for package releases.
+The compatibility boundary covers documented library exports, supported Node
+majors, command inputs/exit behavior, settings and persisted formats. Provisional
+model semantics remain provisional; a package number does not establish universal
+model conformance. Document migration requirements for breaking changes.
+
+| Stage | Breaking change | Compatible feature | Compatible fix |
+| --- | --- | --- | --- |
+| Before 1.0 | Increment minor, reset patch | Increment minor, reset patch | Increment patch |
+| From 1.0 | Increment major, reset minor/patch | Increment minor, reset patch | Increment patch |
+
+Before 1.0, this is a project compatibility convention stronger than SemVer's
+allowance for initial development. A major release of 1.0 requires an explicit
+compatibility decision, not simply a successful build. Prereleases use a suffix
+such as `-experimental.1` or `-rc.1`; increment it for changed prerelease bytes.
+Never reuse a released number. Release versions exclude `+build` metadata to
+avoid distinct Git tags representing the same npm version identity.
+
+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 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 the scoped package.
+- Release candidates use explicit `next`; they must not update `latest`.
+- 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.
+
+## One version, one commit, one release
+
+After release authorization, use a clean, reviewed commit with the approved
+version. Create one annotated `vVERSION` Git tag pointing to its full commit SHA;
+never move, overwrite or delete a release tag. Create the corresponding GitHub
+Release as a draft with `target_commitish` explicitly set to that SHA and the
+prerelease flag matching the version. Do not use a moving branch as the target.
+
+Enable [GitHub release immutability](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/prevent-release-changes)
+before publishing a release. Attach all evidence before finalizing the draft:
+GitHub then locks its tag and assets. The verifier rejects published releases
+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 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 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
+
+From the clean source checkout corresponding to the retained candidates, with
+Node 22/24/26, Git, POSIX `tar`, and GitHub CLI authenticated for read access:
+
+```sh
+npm run check:version
+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, 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
+`npmPublication`/`provenance` values of `"not checked"`. No files or remote state
+are changed. Published releases also require immutability and non-private archives.
+
+For offline checking of a previously saved raw GitHub REST release response:
+
+```sh
+npm run check:release -- /path/to/candidates /path/to/release.json
+```
+
+This deliberately reports `evidence: "offline metadata rehearsal"`. It does not
+contact GitHub or verify a remote tag. Handwritten or stale JSON is not live
+release evidence. The report is also not a reproducible-build proof: validating
+its claimed revision cannot prove arbitrary supplied artifacts were built from
+that revision. Authenticated build provenance and registry readback remain
+required. This checker remains read-only. The separate [release workflow](npm-release.md)
+performs explicitly selected publication; registry permissions remain external.
+
+## Authentication, provenance and incomplete releases
+
+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 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
+
+Maintainer preparation: provide this branch, installed dependencies and the
+candidate setup from [the distribution guide](npm-distribution.md#build-and-inspect-candidates).
+No npm credentials, real Git tag, GitHub Release or global-install change is needed.
+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.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 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
+  ```
+
+  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 the scoped package; `experimental`
+  and `next` do not silently promote `latest`.
+- [ ] Report **Pass / Fail / Blocked**, Node/npm versions, report revision and
+  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.
+
+Automated technical evidence: `tests/version.test.mjs` changes a copied installed
+manifest to `0.7.3-rc.2` and asserts CLI readback; `tests/release.test.mjs` uses
+throwaway Git repositories, tags, archives and metadata to exercise success and
+rejection paths. These tests are synthetic, not a real GitHub Release or registry
+publication. Agent rehearsal and human acceptance remain separate.

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.