@t275005746/gse 0.1.0

package/references/host-adapters.md

@@ -0,0 +1,119 @@
+# Host Adapters
+
+Use this when a project needs GSE to work across Codex, Claude Code, Hermes/AION-style runtimes, WorkBuddy, Copilot-style agents, Gemini-style agents, or another agent host. Use `references/compatibility.md` to check host support status and adoption evidence before making capability claims.
+
+## Core Rule
+
+`.gse/` is the portable source of truth. Host-specific folders are adapters.
+
+Adapters may expose commands, hooks, skills, MCP servers, indexes, or local UI metadata for one host, but they must point back to `.gse/` for project policy, goals, evidence, quality gates, and learning rules.
+
+## Adapter Decision
+
+Create or update a host adapter only when at least one condition is true:
+
+- The host has a real folder, command, hook, skill, MCP, index, or plugin mechanism.
+- The project already has host-specific rules that future agents need to find.
+- A host-specific capability needs a short pointer to `.gse/` to avoid duplicate policy.
+- A migration is needed from an existing `.claude/`, `.codex/`, `.agents/`, or runtime-specific workflow into `.gse/`.
+
+Do not create host folders just for decoration. If the host capability is unknown, document it as `unknown` in `.gse/project-profile.md` or `.gse/tooling.md`.
+
+## Supported Host Shapes
+
+| Host shape | Common adapter location | Adapter should contain | Must not contain |
+|---|---|---|---|
+| Codex-style | `.codex/`, Codex skills, MCP config | Pointer to `.gse/`, skill routing notes, MCP/index notes when verified | Full duplicate goal map or stale project rules |
+| Claude Code-style | `.claude/commands/`, `.claude/agents/`, `.claude/hooks/` | Command/agent/hook entrypoints that read `.gse/` first | Independent process constitution that conflicts with `.gse/` |
+| Hermes/AION-style runtime | runtime skills, worker adapters, memory/tool substrate docs | Runtime bridge notes and internal capability mapping | User-facing product identity or runtime leakage |
+| WorkBuddy/other IDE agents | local docs, plugin settings, task templates | How that host finds `.gse/` and which tools are verified | Claims that unsupported subagent or tool APIs exist |
+| Copilot/Gemini-style assistants | repository instructions, workspace docs | Short instruction to use `.gse/project-profile.md` and relevant gates | Host-specific long workflow copies |
+
+## Adapter Contents
+
+Use `assets/templates/host-adapter.md` for each adapter note.
+
+For command adapters, use:
+
+```text
+node <gse-skill>/scripts/generate-command-adapter.mjs --target <project-root> --host claude|codex|hermes|workbuddy|copilot|gemini|generic|all
+```
+
+This creates the smallest host command pointer available for the selected host. Generated files must still point back to `.gse/`.
+
+Generated command adapter locations:
+
+| Host | Generated path | Native slash-command claim |
+|---|---|---|
+| Claude Code-style | `.claude/commands/gse.md` | yes, file-shape only; runtime proof still needs a host invocation record |
+| Codex-style | `.codex/gse-command.md` | no |
+| Hermes/AION-style runtime | `.gse/host-adapters/hermes-runtime.md` | no |
+| WorkBuddy-style IDE agent | `.gse/host-adapters/workbuddy.md` | no |
+| GitHub Copilot-style assistant | `.github/copilot-instructions.md` | no |
+| Gemini-style assistant | `GEMINI.md` | no |
+| Generic or unknown agent host | `.gse/host-adapters/generic-agent.md` | no |
+
+The Hermes, WorkBuddy, Copilot, Gemini, and generic adapters are portable pointers. They exist to prevent host workflow drift, not to prove runtime support.
+
+For real host execution evidence, use:
+
+```text
+node <gse-skill>/scripts/record-host-invocation.mjs --root <skill-or-project> --host <host> --invocation-method <method> --evidence-owner <owner> --evidence <thread-or-log> --portable-text-command true --native-slash-command false
+```
+
+Then run:
+
+```text
+node <gse-skill>/scripts/audit-host-runtime-invocations.mjs --root <skill-or-project>
+```
+
+Before release handoff or cross-host claims, run the fixture drill:
+
+```text
+node <gse-skill>/scripts/audit-host-runtime-invocation-drill.mjs --root <skill-or-project>
+```
+
+The drill writes temporary records for Claude, Codex, Hermes/AION-style, WorkBuddy, and generic hosts, then audits native versus portable evidence counts. It proves the record/audit mechanics only; it does not prove real host runtime support.
+
+Generated adapters are not runtime proof. A host capability becomes verified only when a persistent host invocation record exists and the audit can parse it.
+
+Minimum fields:
+
+- Host name and adapter path.
+- Source of truth: always `.gse/` unless the project explicitly says otherwise.
+- Verified capabilities: commands, hooks, MCP, LSP/index, subagents, browser, CI.
+- Unverified or unavailable capabilities.
+- How to start meaningful work in this host.
+- Safety and permissions.
+- Drift check owner or cadence.
+
+## Tool Status Rules
+
+Use the same vocabulary as `references/tool-adapters.md`:
+
+- `verified`: checked in this project or trusted local docs.
+- `documented`: present in docs or config, not tested in this session.
+- `unknown`: not confirmed.
+- `unavailable`: expected but missing or failing.
+
+Never mark a host capability as `verified` because another host has it. Subagents, hooks, MCP, and browser tools are host-specific.
+
+## Drift Prevention
+
+Use `references/drift-audit.md` when host-specific folders, hooks, skills, MCP, subagents, runtime adapters, or capability claims may have drifted from `.gse/`.
+
+When adding a host adapter:
+
+1. Keep policy in `.gse/` and link back from the host folder.
+2. Copy only the shortest host-specific command or pointer needed.
+3. Add the adapter to `.gse/project-profile.md` under `Agent Host Adapters`.
+4. Add any verified commands to `.gse/tooling.md`.
+5. If the adapter changes task routing, update `.gse/goal-map.md` or `.gse/quality-gates.md` only once in the portable layer.
+
+## Review Checklist
+
+- Does the adapter point to `.gse/` before host-specific instructions?
+- Are verified and unverified capabilities separated?
+- Are secrets and write-capable tools documented without exposing credentials?
+- Is there only one authoritative goal map and evidence location?
+- Can a future agent using a different host still follow the project workflow?

package/references/learning-system.md

@@ -0,0 +1,35 @@
+# Learning System
+
+Learnings keep long projects from repeating mistakes.
+
+## Capture When
+
+- User corrects an assumption.
+- A command, tool, API, or integration fails unexpectedly.
+- A bug root cause was non-obvious.
+- A recurring workflow can be shortened or hardened.
+- A missing quality gate allowed a defect through.
+
+## Do Not Capture
+
+- Raw chain of thought.
+- Temporary attempts.
+- Long command output.
+- One-off details unlikely to help future work.
+
+## Upgrade Rule
+
+Use `references/drift-audit.md` when a repeated lesson suggests stale docs, stale project-profile facts, stale host adapters, stale tool assumptions, or stale evidence state.
+
+- First occurrence: learning note.
+- Second occurrence: checklist or template update.
+- Third occurrence: project rule or quality gate.
+- Fifth occurrence: script, test, or dedicated skill.
+
+## Suggested Stores
+
+- `.gse/learnings.md` for portable project lessons.
+- `.learnings/` when the project already uses that convention.
+- `AGENTS.md` for durable project rules.
+- ADRs for architectural decisions.
+

package/references/marketplace-discovery.md

@@ -0,0 +1,46 @@
+# Marketplace Discovery
+
+Use this when preparing GSE for a public catalog, skill marketplace, plugin listing, GitHub release page, or internal agent-workflow registry.
+
+Discovery metadata should help people find and evaluate GSE without overstating trust.
+
+## Required Metadata
+
+- Name and display name.
+- Short tagline and summary.
+- Categories and keywords that describe the workflow naturally.
+- Entrypoints for humans and agents.
+- Validation commands.
+- Distribution and signing references.
+- Host support status with honest labels.
+- Boundaries and unverified claims.
+
+The canonical local metadata file is:
+
+```text
+assets/marketplace/gse-listing.json
+```
+
+## Search Language
+
+Use normal explanatory language around terms such as agentic engineering, spec-driven development, SDD, AI coding agents, goal maps, evidence gates, OpenSpec-style changes, and Superpowers-style execution. Do not add isolated search-term blocks that read like keyword stuffing.
+
+## Trust Boundary
+
+Discovery metadata is not marketplace approval.
+
+A listing can be:
+
+- `result`: drafted metadata exists.
+- `verified`: metadata passes local audit and matches package validation.
+- `accepted`: the target marketplace, catalog owner, or release owner accepts it.
+
+## Validation
+
+Run:
+
+```text
+node <skill>/scripts/audit-marketplace-discovery.mjs --root <skill> --json
+```
+
+For release trust, also use `references/release-trust.md`.

package/references/model-routing.md

@@ -0,0 +1,103 @@
+# Model Routing
+
+Use this when GSE work needs to choose a model, provider, hosted tool, local tool, browser agent, worker, or role-specific agent capability.
+
+## Core Rule
+
+Route by capability first, then cost, latency, privacy, context size, tool use, reliability, and evidence.
+
+Do not hard-code one provider, one model family, or one host as the GSE default. Projects may define preferred providers, but GSE must preserve a portable fallback path.
+
+## Capability-First Selection
+
+Define the task capability before picking a model:
+
+| Capability | Typical use | Routing preference |
+|---|---|---|
+| Fast classification | triage, route selection, small labels | lowest reliable latency/cost |
+| Code location | symbol search, call chains, existing tests | LSP/index/search before stronger model reasoning |
+| Mechanical edit | narrow transforms, boilerplate, local fixes | lower-cost coding-capable model if verification is strong |
+| Implementation | bounded code slice, tests, integration | standard coding model with project context |
+| Architecture/root cause | invariants, multi-file reasoning, debugging | highest-reasoning model available and approved |
+| Review/QA | spec compliance, security, regressions, UI evidence | independent reviewer model or fresh context when risk is high |
+| Long context synthesis | session working set, docs, logs, migration notes | model with adequate context and summarization behavior |
+| Tool/worker execution | browser, shell, MCP, CI, queue, runtime worker | verified host/tool adapter, not just model choice |
+
+## Status Vocabulary
+
+Keep model availability separate from model behavior.
+
+- `documented`: project docs, provider config, or host settings mention the model/tool.
+- `verified`: this session or project evidence ran the model/tool successfully for the relevant capability.
+- `unknown`: no trustworthy evidence yet.
+- `unavailable`: expected model/tool is missing, blocked, failing, or forbidden.
+
+A documented model is not verified. A verified chat response does not verify tool use, long context, latency, cost, or privacy behavior.
+
+## Routing Inputs
+
+Record these in `.gse/project-profile.md`, `.gse/tooling.md`, or a host adapter when relevant:
+
+- Provider or host:
+- Model/tool id:
+- Capability:
+- Status: documented | verified | unknown | unavailable
+- Evidence path or command:
+- Cost tier:
+- Latency expectation:
+- Context limit or practical context budget:
+- Tool-use support:
+- Privacy/security boundary:
+- Fallback:
+- Known failure modes:
+
+## Decision Order
+
+1. Use project-specific routing rules if they exist and do not conflict with current user instruction.
+2. Prefer verified local tools for code location, tests, browser smoke, and CI before spending model reasoning.
+3. Choose the cheapest/fastest model that can satisfy the capability with adequate verification.
+4. Escalate to a stronger model when there is a clear reasoning, context, safety, or integration gap.
+5. Use fresh context for review, QA, or high-risk architecture when current-session context may bias the result.
+6. Fall back to a documented or generic model only when the task risk is low or verification can catch mistakes.
+7. Record residual risk when model behavior is unknown or only structurally verified.
+
+## Fallback Rules
+
+- If preferred model is unavailable, use the next project-approved model with the same capability class.
+- If tool-use support is unavailable, switch to manual shell/browser/CI verification when possible.
+- If long-context support is unavailable, build a smaller working set and record omitted context.
+- If privacy constraints forbid remote models, use local tools, local models, or ask for a project-approved path.
+- If cost is high, reduce context, split the task, or use lower-tier models for locator/QA roles.
+- Do not claim a fallback preserved quality unless focused evidence proves it.
+
+## Evidence Requirements
+
+For model routing claims, record:
+
+```text
+Capability:
+Chosen model/tool:
+Why this route:
+Status: documented | verified | unknown | unavailable
+Cost/latency notes:
+Context/tool-use notes:
+Privacy/security notes:
+Fallback:
+Evidence:
+Residual risk:
+```
+
+## What Not To Do
+
+- Do not route all tasks to the strongest model by default.
+- Do not route all tasks to the cheapest model when failure would be expensive.
+- Do not treat provider marketing claims as project evidence.
+- Do not expose secrets, raw provider payloads, hidden reasoning, or private tool traces in user-facing output.
+- Do not confuse model routing with provider adapter implementation.
+
+## Project Integration
+
+- `references/project-profile.md` records project-approved providers, model/tool ids, privacy limits, and fallback policy.
+- `references/tool-adapters.md` records availability and verification status for host tools and model-backed tools.
+- `references/host-adapters.md` records host-specific model, subagent, MCP, browser, and worker capabilities.
+- `references/evidence-taxonomy.md` decides whether routing evidence is result, verified, or accepted.

package/references/open-source-defaults.md

@@ -0,0 +1,39 @@
+# GSE Open-Source Defaults
+
+Use this reference when preparing GSE for a public repository or when a project asks to follow the mainstream open-source path.
+
+## Recommended Default
+
+GSE's owner-approved default route is:
+
+- License: MIT.
+- Repository: public GitHub repository.
+- CI: GitHub Actions with required checks.
+- Security: `SECURITY.md` plus GitHub Security Advisory or another owner-approved public disclosure path.
+- Release channel: GitHub Release first; package registry or marketplace only after real publication evidence exists.
+- Command UX: portable `/gse ...` commands, with native slash-command claims only after a host runtime record proves native execution.
+
+## Why This Default
+
+- MIT is widely understood by open-source tool users and keeps integration friction low.
+- GitHub public repository plus GitHub Actions gives public, linkable evidence for repository settings and CI.
+- GitHub Release provides a simple first public channel without pretending a registry or marketplace approved the package.
+- Portable `/gse ...` command semantics work across hosts even when native slash-command APIs differ.
+
+## Claim Boundaries
+
+- A local `LICENSE` file proves the license text exists; accepted license status requires an owner-approved release record.
+- A local GitHub Actions workflow file does not prove public CI. Use a real public run URL and `scripts/record-public-ci-run.mjs`.
+- A local `SECURITY.md` does not prove a public security contact. Use `scripts/record-public-security-contact.mjs` after the disclosure path is public and owner-approved.
+- A generated package or release bundle does not prove public publication. Use `scripts/record-public-channel-publication.mjs` after a real channel URL exists.
+- Generated host adapter pointers do not prove native slash commands. Use `scripts/record-host-invocation.mjs` with real host evidence.
+
+## Minimal Public Release Order
+
+1. Record the owner-approved MIT license decision.
+2. Publish or mirror GSE into a public GitHub repository.
+3. Enable repository settings: issues, pull requests, security policy visibility, branch protection, required checks, review before merge, conversation resolution, force-push restriction, and deletion restriction.
+4. Run public GitHub Actions and record the run URL, commit SHA, branch, and required checks.
+5. Create a GitHub Release and record the release URL.
+6. Record host runtime invocation evidence for each claimed host.
+7. Re-run final readiness and public acceptance audits.

package/references/operating-model.md

@@ -0,0 +1,52 @@
+# Operating Model
+
+Use the same loop for every task, scaled by task level.
+
+## 1. Goal
+
+Identify the project goal, user outcome, current priority, and non-goals.
+
+For long-running work, bind to `.gse/goal-map.md` or the project's existing goal map.
+
+## 2. Spec
+
+Define boundaries before implementation:
+
+- Inputs and outputs
+- UI/API/state behavior
+- Error and recovery behavior
+- Permissions and privacy boundaries
+- Acceptance criteria
+- Test or smoke plan
+
+Do not over-spec Level 1 tasks.
+
+## 3. Execute
+
+Use the smallest verifiable slice.
+
+- Locate code with `rg`, `rg --files`, LSP, or an index before editing.
+- Follow existing patterns.
+- Keep unrelated refactors out.
+- Use subagents only when actual dispatch tools exist and ownership is clear.
+- Use `references/file-ownership.md` before editing dirty files, shared files, or files assigned to another role.
+- Avoid making every internal state transition its own product slice. When several small states only matter as one user-visible chain, merge them and verify the chain.
+
+## 4. Evidence
+
+Completion needs evidence appropriate to the risk:
+
+- Unit/component/contract test
+- API smoke
+- Browser or Playwright smoke
+- Build/typecheck/lint
+- Screenshot or trace for UI
+- Commit hash or change summary
+
+Choose the gate profile from `references/task-levels.md` and `references/quality-gates.md`. A small docs or state slice should not pay the same verification cost as a release/install/cross-host slice. Conversely, release, public contract, install, and host-runtime claims need hard gates and cannot be proven by narrow tests alone.
+
+## 5. Learn
+
+Record reusable lessons when a failure, correction, tool gap, repeated bug, or better process is discovered.
+
+Escalate repeated lessons into quality gates or project rules.

package/references/packaging.md

@@ -0,0 +1,277 @@
+# Packaging And Maintenance
+
+Use this when preparing GSE itself for handoff, update, local installation, or a versioned internal release.
+
+Use `references/adoption-recipes.md` for applying or updating GSE inside a target project after the skill package itself is validated.
+
+This is a packaging readiness guide, not a registry publication process. Do not claim marketplace distribution, host plugin support, signing, open-source license acceptance, or v1.0 acceptance unless that evidence exists. Use `references/public-release.md` before public GitHub, marketplace, catalog, registry, or external package handoff.
+
+## Package Boundary
+
+The GSE skill package includes:
+
+- `package.json` as Node package metadata for local packing, CLI bin exposure, and future registry handoff.
+- `SKILL.md` as the small entrypoint.
+- `CHANGELOG.md` as the public-release change history and unsupported-claims boundary.
+- `CONTRIBUTING.md`, `SECURITY.md`, and `SUPPORT.md` as public repository collaboration, vulnerability-reporting, and support boundaries.
+- `.github/workflows/validate-gse.yml` as the portable GitHub Actions validation template for public repository use.
+- `.github/PULL_REQUEST_TEMPLATE.md` and `.github/ISSUE_TEMPLATE/` as evidence-first public collaboration templates.
+- `references/` as progressive-disclosure guidance.
+- `scripts/` as repeatable audits, generators, discovery, validation, and forward-test probes.
+- `assets/templates/` as reusable project artifacts.
+- `assets/marketplace/` as portable discovery metadata for catalogs and marketplaces.
+- `examples/` as lightweight adoption fixtures.
+- `agents/openai.yaml` as optional host UI metadata.
+- `.gse/` as the GSE self-development source of truth.
+
+Do not package temporary output, command logs, screenshots, secrets, generated cache folders, `.learnings/`, or host-specific local credentials.
+
+Generated package and release manifests must not expose the packager's local absolute source path. Keep local paths in command output only, not in distributable metadata.
+
+## Version And Release Label
+
+GSE currently uses an internal readiness label rather than a published semver package.
+
+Release labels should use this format until a real package manager or registry exists:
+
+```text
+gse-internal-YYYY-MM-DD-N
+```
+
+Increment `N` for multiple release candidates on the same day.
+
+Use semver only after there is a maintained distribution channel and backward-compatibility policy.
+
+## Release Validation Gate
+
+Before handing off or calling a GSE package release-ready, run:
+
+```text
+node <skill>/scripts/validate-gse.mjs --root <skill>
+```
+
+The release is not ready if validation fails, if the skill validator is skipped unexpectedly, or if a required evidence gate is only `result` when the release level requires `verified` or `accepted`.
+
+`validate-gse.mjs` currently covers structural self-audit, project bootstrap smoke, fixture adoption, existing-repo adoption, host adapter generation, compatibility matrix, documented fixture forward-test, fresh-session readiness, local package/install distribution audit, remote URL distribution integrity audit, package signing and verification audit, release trust policy, public release metadata, release bundle generation, open-source repository readiness, CI workflow readiness, public collaboration templates, marketplace discovery metadata, host UI invocation readiness, skill metadata validation, and BOM scanning.
+
+## Distribution Audit Profiles
+
+Before public handoff or registry preparation, verify Node package metadata:
+
+```text
+node <skill>/scripts/audit-npm-package-metadata.mjs --root <skill> --json
+node <skill>/scripts/audit-npm-tarball-install.mjs --root <skill> --json
+node <skill>/scripts/audit-npm-publish-dry-run.mjs --root <skill> --json
+npm pack --dry-run --json
+```
+
+The metadata audit proves package metadata and dry-run pack contents. The tarball install audit creates a real local npm tarball, installs it into a clean temporary consumer project, runs the installed `gse` bin, and runs an installed README audit. The publish dry-run audit checks npm publication metadata, CLI bin preservation, required runtime files, integrity fields, and harmful metadata auto-correction warnings. These checks do not publish to npm, reserve a package name, verify a public repository, or prove registry approval.
+
+Use the right distribution profile for the claim:
+
+```text
+node <skill>/scripts/audit-distribution.mjs --root <skill> --profile smoke
+node <skill>/scripts/audit-remote-distribution.mjs --root <skill> --profile smoke
+node <skill>/scripts/validate-gse.mjs --root <skill> --distribution-profile smoke
+```
+
+`smoke` verifies package creation, install, installed entrypoints, CLI status, remote URL install, and remote integrity/tamper behavior. It skips the nested installed-copy `validate-gse` run.
+
+Use `full` before release, package handoff, install/update claims, or when the installed copy itself must be validated:
+
+```text
+node <skill>/scripts/validate-gse.mjs --root <skill> --distribution-profile full
+```
+
+## CI Workflow Template
+
+GSE includes a GitHub Actions workflow template at `.github/workflows/validate-gse.yml`.
+
+The template runs:
+
+```text
+node scripts/validate-gse.mjs --root . --skip-skill-validator --json
+node scripts/audit-final-readiness.mjs --root . --json
+node scripts/audit-final-acceptance-packet.mjs --root . --json
+```
+
+Run the local CI readiness audit with:
+
+```text
+node <skill>/scripts/audit-ci-readiness.mjs --root <skill>
+```
+
+This verifies the workflow file, trigger coverage, Node setup, validation commands, and final-readiness boundary checks. It does not prove a real public GitHub Actions run, branch protection, required status checks, or marketplace CI policy.
+
+## Release Bundle
+
+Use a release bundle when handing GSE to another host, another repository, or a maintainer who needs the install commands, validation checklist, public-release record, and unsupported-claims boundary in one directory:
+
+```text
+node <skill>/scripts/generate-release-bundle.mjs --root <skill> --label <release-label> --out <bundle-dir>
+```
+
+For a focused bundle check, run:
+
+```text
+node <skill>/scripts/audit-release-bundle.mjs --root <skill>
+```
+
+This verifies that the bundle contains a release summary, install commands, validation checklist, public-release record, handoff files, manifest, and owner action plan. The bundle generator creates a fresh release status manifest and owner action plan during bundle creation instead of trusting stale cached acceptance files. The audit writes to an isolated temporary directory so it does not mutate the canonical release bundle path during validation. It still does not publish GSE, choose a license, approve a marketplace listing, or prove host-native slash-command support.
+
+## Release Status Manifest
+
+Use the release status manifest when another host, CI job, marketplace checklist, or maintainer needs a machine-readable summary of GSE readiness:
+
+```text
+node <skill>/scripts/generate-release-status-manifest.mjs --root <skill> --out <skill>/.gse/acceptance/release-status-manifest.json --force
+node <skill>/scripts/audit-release-status-manifest.mjs --root <skill>
+```
+
+The manifest summarizes verified rows, owner-required rows, external-required rows, install/distribution status, public acceptance gates, host runtime evidence counts, host runtime fixture drill status, and verification commands. It is generated from current audits and records; it does not create owner decisions, external publication, public CI, marketplace approval, or native slash-command evidence.
+
+## Release Owner Action Plan
+
+Use the owner action plan when a human owner or maintainer needs the next concrete public-release actions grouped by responsible party:
+
+```text
+node <skill>/scripts/generate-release-owner-action-plan.mjs --root <skill> --force --json
+node <skill>/scripts/audit-release-owner-action-plan.mjs --root <skill> --json
+node <skill>/scripts/audit-release-owner-action-plan-drill.mjs --root <skill> --json
+```
+
+The plan is generated from `.gse/acceptance/release-status-manifest.json`. It groups pending gates by project owner, repository owner, external CI, external registry, external marketplace, and host runtime. It includes the record command and required evidence for each gate. It does not select a license, configure a repository, run public CI, publish a package, approve a marketplace listing, or prove native slash-command support.
+
+The drill runs the plan path in a temporary fixture: it generates the manifest and plan, creates accepted fixture records for every owner/external gate family, verifies final readiness promotes to `publicAccepted: verified`, verifies the public acceptance doctor reports zero pending gates, and then removes the fixture. This proves the workflow mechanics without claiming real public acceptance.
+
+## Local Package And Install
+
+Use this path before claiming GSE can be copied or installed outside its current development folder:
+
+```text
+node <skill>/scripts/package-gse.mjs --root <skill> --out <package-dir> --label <release-label>
+node <skill>/scripts/install-gse.mjs --source <package-dir> --target <install-skill-dir>
+node <install-skill-dir>/scripts/validate-gse.mjs --root <install-skill-dir> --skip-skill-validator --skip-distribution --skip-completion-readiness
+```
+
+For a one-command local distribution proof, run:
+
+```text
+node <skill>/scripts/audit-distribution.mjs --root <skill>
+```
+
+This proves file-based packaging, install, and installed-copy validation. It still does not prove registry publication, remote-machine install, signing, shell completion, or marketplace discovery.
+
+## Remote URL Install And Integrity
+
+GSE packages include a `gse-package-manifest.json` with `sha256` hashes for packaged files.
+
+Install from a URL-shaped package source with:
+
+```text
+node <skill>/scripts/install-gse.mjs --source-url <file-or-http-package-url> --target <install-skill-dir>
+```
+
+Run the focused remote distribution audit with:
+
+```text
+node <skill>/scripts/audit-remote-distribution.mjs --root <skill>
+```
+
+This starts a temporary HTTP package source, installs from `--source-url`, validates the installed copy, then tampers with a package file to verify the integrity gate fails. It proves URL install and manifest integrity behavior locally. It still does not prove public registry publication, trusted signing, marketplace discovery, or remote-machine network conditions.
+
+## Signing And Verification
+
+Use Ed25519 signing when a package needs tamper evidence beyond raw file hashes:
+
+```text
+node <skill>/scripts/sign-gse-package.mjs --package <package-dir> --private-key <private.pem> --public-key <public.pem>
+node <skill>/scripts/verify-gse-package.mjs --package <package-dir> --public-key <public.pem>
+node <skill>/scripts/install-gse.mjs --source <package-dir> --target <install-skill-dir> --public-key <public.pem>
+```
+
+For local audit keys only:
+
+```text
+node <skill>/scripts/sign-gse-package.mjs --package <package-dir> --private-key <private.pem> --public-key <public.pem> --generate-key
+```
+
+Run the focused signing audit with:
+
+```text
+node <skill>/scripts/audit-signing.mjs --root <skill>
+```
+
+This proves signing mechanics, signature verification, signed install, and tamper rejection. It does not prove maintainer identity, public key custody, transparency logs, marketplace trust, or a production release policy.
+
+For public or shared releases, also complete `references/release-trust.md` and `assets/templates/release-trust-record.md`. This is the Release Trust record for the package. A package can be signed and verified without being trusted; trusted release status requires owner acceptance, public key fingerprint publication, custody rules, rotation policy, and revocation path.
+
+For public open-source releases, also complete `references/public-release.md` and `assets/templates/public-release-record.md`. GSE must not choose a license by guessing; accepted public release requires an owner-selected license or an explicit `not-public` decision.
+
+## Marketplace Discovery
+
+Use `references/marketplace-discovery.md` and `assets/marketplace/gse-listing.json` when preparing a public listing, catalog entry, plugin page, or marketplace submission.
+
+Run:
+
+```text
+node <skill>/scripts/audit-marketplace-discovery.mjs --root <skill> --json
+```
+
+This verifies local discovery metadata and search-language fit. It does not prove marketplace approval, public search indexing, registry publication, maintainer identity, or host-native installation.
+
+## Release Notes
+
+Use `references/release.md` as the general release policy. For GSE skill releases, keep notes short:
+
+```text
+Release label:
+Date:
+Readiness: not ready | result | verified | accepted
+Changed:
+Validation:
+Compatibility impact:
+Migration or rollback:
+Known risks:
+Follow-up slices:
+```
+
+Rules:
+
+- Link to `.gse/evidence/YYYY-MM-DD.md` instead of pasting long command output.
+- Separate user-facing workflow changes from internal script/refactoring changes.
+- Mark unavailable or unverified host tools honestly.
+- Keep true fresh-session acceptance separate from fresh-session readiness.
+
+## Install Or Update Handoff
+
+For a local handoff, provide:
+
+- Skill path: `<install-skill-dir>` or the target install path.
+- Release label or date.
+- Validation command and latest result.
+- Evidence log path.
+- Known residual risks.
+- Next slice from `.gse/current-slice.md`.
+
+For project-local GSE updates or release-readiness changes, use `assets/templates/update-release-acceptance-record.md` to preserve local decisions, changed files, commands run, rollback notes, owner gate, accepted-by status, and residual risks.
+
+If copying GSE to another machine or host, run validation after copy and record the result in that environment. Host-specific capabilities remain `unknown` until checked there.
+
+## Rollback
+
+For low-risk GSE documentation/script changes, rollback is file-level revert of the touched artifacts plus re-running `validate-gse.mjs`.
+
+For scaffold, generator, or template changes that may affect downstream projects, also record:
+
+- Which generated files or adapters may need regeneration.
+- Whether existing project `.gse/` folders are compatible.
+- Whether host adapters need manual review.
+
+## Readiness Status
+
+- `result`: packaging notes or release artifacts exist.
+- `verified`: `validate-gse.mjs` passes and release notes identify residual risks.
+- `accepted`: required owner, fresh-session, release policy, or distribution gate accepts the release.
+
+Do not call a release accepted only because local validation passed unless the current release policy explicitly says local validation is sufficient.