skillpacks 0.1.1 → 0.1.2

package/docs/skillpacks-npm-distribution.md

@@ -2,32 +2,37 @@
 
 ## Approval Summary
 
-Source alignment page: `alignment/idea-scope-brief-npm-distribution.html` (historical strategy context). Current package usage reference: `alignment/skillpacks-npm-package-walkthrough.html`.
+Source alignment page: `alignment/idea-scope-brief-npm-distribution.html` (historical strategy context). Current package usage reference: `alignment/gskp-npm-package-walkthrough.html`.
 
 Approved decisions:
 
 - Primary path: hybrid, starting with COA A and evolving toward COA B/C only when demand justifies it.
-- Public npm/CLI name: `skillpacks`.
+- Primary public npm package: `skillpacks`.
+- Scoped alias npm package: `@glexcorp/gskp`.
 - Version granularity: skill-level versioning remains authoritative for user pinning.
 - Deck installation: COA B/C-shaped metadata first. Decks should be represented as curated package lists and registry tags; the initial COA A monolith may materialize those selections locally, but deck behavior should not be hard-coded as monolith-only presets.
 - Artifact route: write the detailed design doc in `docs/` first, then use it as the implementation roadmap.
 
-Current npm check on 2026-06-08:
+Current npm check on 2026-06-12:
 
-- `npm view skillpacks --json` returned `E404`, so the unscoped package name appears unclaimed or inaccessible to this machine.
-- `npm view @skillpacks/cli --json` and `npm view @skillpacks/core --json` returned `E404`; that does not prove npm organization availability, but no packages under those names are visible.
+- `npm view gsp --json` returned an existing external package at version `0.5.4`, so `gsp` should not be used.
+- `npm view gsk --json` returned an existing external package at version `0.0.2`, so `gsk` should not be used.
+- `npm view skp --json` returned an existing external package at version `1.0.0`, so `skp` should not be used.
+- `npm view gskp --json` returned `E404`, so the unscoped package name appears unclaimed or inaccessible to this machine.
 - `npm view agentic-skills --json` returned an existing external package at version `2.5.1`, so `agentic-skills` should not be used as this repo's public npm package name.
+- `npm view skillpack --json` returned an existing unrelated package at version `0.1.3`; warn against the singular typo, but keep `skillpacks` as the primary route because it already exists and has users.
 
-Publication status on 2026-06-10:
+Publication status:
 
-- `skillpacks@0.1.0` is published publicly on npm with `latest` pointing to `0.1.0`.
-- Package metadata uses `license: MIT`, repository `git+https://github.com/GeorgeQLe/agentic-skills.git`, `repository.directory: packages/skillpacks`, bugs URL `https://github.com/GeorgeQLe/agentic-skills/issues`, and homepage `https://github.com/GeorgeQLe/agentic-skills#readme`.
-- Registry tarball evidence: `skillpacks-0.1.0.tgz`, 2,349 files, 31,323,992 bytes unpacked, shasum `9ab8925b5f8d3dc39f1caa9c50609fb8df6df1f2`, integrity `sha512-TyZFnm9HjaV8E0yTN1EPRuh1BZDWt/Hcn316omlXvAVhLFpWkP191BaKzw/wmCjRkEm14RF2WkWJ6XSlusDKHg==`.
-- Published-package verification passed with `npx skillpacks@latest list`, temp-project `install code-quality`, temp-project `install quality-sweep`, temp-project `install-deck game-afps`, and the git-checkout `scripts/pack.sh list` path.
+- `skillpacks@0.1.0` and `skillpacks@0.1.1` were published publicly on npm before the short-name change.
+- Source package metadata is `skillpacks`.
+- Each release also publishes `@glexcorp/gskp` as a scoped alias from the same built artifact and version.
+- Both packages expose both binaries: `skillpacks` and `gskp`.
+- The public verification targets are `npx skillpacks@latest list`, `npx @glexcorp/gskp@latest list`, temp-project `install code-quality`, temp-project `install quality-sweep`, temp-project `install-deck game-afps`, and the git-checkout `scripts/pack.sh list` path.
 
 ## Product Shape
 
-`skillpacks` becomes the public installer and CLI for this repository's markdown skill library. The first npm release should not restructure the repository into many packages. It should package the current repository content needed to install skills and expose a Node entry point that can drive the existing install model.
+`skillpacks` is the primary public installer and CLI package for this repository's markdown skill library. `@glexcorp/gskp` is a scoped alias package for users who prefer the `gskp` identity. The first npm release should not restructure the repository into many packages. It should package the current repository content needed to install skills and expose a Node entry point that can drive the existing install model.
 
 The initial user experience should be:
 
@@ -40,22 +45,37 @@ npx skillpacks doctor
 npx skillpacks refresh
 ```
 
-`npx skillpacks init` installs the base skill surface into the current repository as local skill roots and records `base_skills: true` in `.agents/project.json`. This makes `npx skillpacks refresh` update base skills from the current package snapshot instead of depending on user-home global installs.
+`npx skillpacks init` installs the base skill surface into the current repository as local skill roots and records `base_skills: true` in `.agents/project.json`. This makes `npx skillpacks refresh` update base skills from the current package snapshot. Base skills are **project-local only** — there is no user-home (global) install path.
 
-Existing users keep using:
+If a machine still has legacy user-home base installs from the retired init path, clean them up with:
 
 ```bash
-./init.sh
+npx skillpacks uninstall-global
+```
+
+This removes only skillpacks-owned installs under `~/.claude/skills` and `~/.codex/skills` and leaves unmanaged directories untouched. Domain packs remain project-local only.
+
+Source-checkout users install base skills project-local the same way and keep using `scripts/pack.sh` for packs:
+
+```bash
+npx skillpacks init
 scripts/pack.sh install business-discovery
 scripts/pack.sh refresh
 ```
 
-The npm path is additive until it proves stable.
+The npm path is now the standard agent-facing install route. The source-checkout commands remain supported for local repository development and compatibility.
+
+Scoped alias examples are equivalent at the same package version:
+
+```bash
+npx @glexcorp/gskp init
+npx @glexcorp/gskp install business-discovery
+```
 
 ## Design Principles
 
 1. Preserve `SKILL.md` as the source format.
-2. Preserve `global/{claude,codex}` and `packs/<pack>/{claude,codex}` as the authoring layout.
+2. Preserve `base/{claude,codex}` and `packs/<pack>/{claude,codex}` as the authoring layout.
 3. Preserve `.agents/project.json` as the project designation file.
 4. Preserve `scripts/pack.sh` while the npm CLI reaches parity.
 5. Keep the first npm release as one package.
@@ -67,7 +87,7 @@ The npm path is additive until it proves stable.
 
 ### Package
 
-The publishable npm package is named `skillpacks` and lives under `packages/skillpacks/`. The repository root stays private workspace metadata for the monorepo.
+The publishable npm package source is named `skillpacks` and lives under `packages/skillpacks/`. The repository root stays private workspace metadata for the monorepo. During release, `./publish.sh` stages two publish directories from `packages/skillpacks/build`: one with `package.json.name = "skillpacks"` and one with `package.json.name = "@glexcorp/gskp"`.
 
 Current package `package.json` shape:
 
@@ -78,6 +98,7 @@ Current package `package.json` shape:
   "description": "CLI and packaged markdown skill library for Claude Code and OpenAI Codex.",
   "type": "module",
   "bin": {
+    "gskp": "bin/skillpacks.mjs",
     "skillpacks": "bin/skillpacks.mjs"
   },
   "repository": {
@@ -93,7 +114,7 @@ Current package `package.json` shape:
     "bin/",
     "src/",
     "dist/",
-    "global/",
+    "base/",
     "packs/",
     "scripts/pack.sh",
     "scripts/skill-links.sh",
@@ -104,8 +125,7 @@ Current package `package.json` shape:
     "README.md",
     "LICENSE",
     "AGENTS.md",
-    "CLAUDE.md",
-    "init.sh"
+    "CLAUDE.md"
   ],
   "license": "MIT",
   "engines": {
@@ -116,6 +136,19 @@ Current package `package.json` shape:
 
 The root `package.json` is private and declares workspaces for `apps/skills-showcase` and `packages/skillpacks`. The public package uses the repository root MIT license and npm metadata links back to `https://github.com/GeorgeQLe/agentic-skills`. The first release can keep runtime dependencies at zero. If argument parsing grows, add one small dependency later instead of pulling in a framework immediately.
 
+Both published packages expose the same binaries:
+
+```json
+{
+  "bin": {
+    "gskp": "bin/skillpacks.mjs",
+    "skillpacks": "bin/skillpacks.mjs"
+  }
+}
+```
+
+Do not use `skillpack` singular; that is an unrelated npm package with a different project format.
+
 ### CLI Entry Point
 
 `packages/skillpacks/bin/skillpacks.mjs` resolves the installed package root with `import.meta.url`, then dispatches commands into either:
@@ -131,10 +164,9 @@ The wrapper must run `scripts/pack.sh` with the user's current working directory
 
 The npm tarball must include:
 
-- `global/**` active core skills and their local archives.
+- `base/**` active core skills and their local archives.
 - `packs/**` active pack skills and their local archives.
 - `scripts/pack.sh` and script helpers it sources, especially `scripts/skill-links.sh`.
-- `init.sh` or an equivalent `init-global` implementation.
 - deck and pack docs used for help output.
 
 The package build script at `packages/skillpacks/scripts/build-package.mjs` stages these files into `packages/skillpacks/build/` before `npm pack`. The staging step must not generate or mutate Skills Showcase assets.
@@ -150,13 +182,13 @@ The tarball should exclude:
 - generated local roots under `.claude/skills` and `.codex/skills`
 - unrelated benchmark output and session artifacts
 
-Skill-level archives inside `global/**/archive/` and `packs/**/archive/` must remain included because pinning depends on them.
+Skill-level archives inside `base/**/archive/` and `packs/**/archive/` must remain included because pinning depends on them.
 
 ## CLI Surface
 
-Phase 3 compatibility decision: keep `scripts/pack.sh` as the canonical git-checkout compatibility wrapper and as the packaged shell fallback for commands that are not yet worth porting. Do not turn `pack.sh` into a thin wrapper over the Node CLI in this phase; that would make the old checkout path depend on the npm package internals before all discovery and init surfaces are ported. Revisit the decision only after `recommend`, `which`, `install-deck`, and global init behavior are either Node-owned or intentionally documented as permanent shell surfaces.
+Phase 3 compatibility decision: keep `scripts/pack.sh` as the canonical git-checkout compatibility wrapper and as the packaged shell fallback for commands that are not yet worth porting. Do not turn `pack.sh` into a thin wrapper over the Node CLI in this phase; that would make the old checkout path depend on the npm package internals before all discovery and init surfaces are ported. Revisit the decision only after `recommend`, `which`, and `install-deck` are either Node-owned or intentionally documented as permanent shell surfaces. (Base init is fully Node-owned and project-local; the user-home global init path has been retired.)
 
-<!-- skillpacks-compatibility-matrix:start -->
+<!-- gskp-compatibility-matrix:start -->
 | Command | Owner | Backend | Requires bash | Requires jq | Notes |
 | --- | --- | --- | --- | --- | --- |
 | `help / --help / --version` | Node-owned | `packages/skillpacks/src/cli/run-pack-script.mjs` | No | No | CLI help and version output from package metadata. |
@@ -165,11 +197,18 @@ Phase 3 compatibility decision: keep `scripts/pack.sh` as the canonical git-chec
 | `status` | Node-owned | Project config/status reader | No | No | Reports project designation and local roots. |
 | `set-mode <mode>` | Node-owned | Project config writer | No | No | Preserves unrelated fields and uses the Node lock helper. |
 | `set-update-mode <mode>` | Node-owned | Project config writer | No | No | Preserves sibling `skill_updates` fields. |
-| `init` | Node-owned | Manifest plus lifecycle helpers | No | No | Installs global-scope manifest entries as project-local base skills and records `base_skills: true`. |
+| `init` | Node-owned | Manifest plus lifecycle helpers | No | No | Installs base-scope manifest entries as project-local base skills and records `base_skills: true`. |
+| `uninstall-global` | Node-owned | Managed marker ownership reader | No | No | Removes legacy skillpacks-owned base installs from `~/.claude/skills` and `~/.codex/skills`; leaves unmanaged directories untouched. |
 | `install <name...>` | Node-owned | Manifest plus lifecycle helpers | No | No | Handles active packs, active skills, aliases, hibernated diagnostics, markers, hashes, and project config writes. |
 | `remove <name...>` | Node-owned | Manifest plus lifecycle helpers | No | No | Handles active pack removal, individual skill removal, and hibernated stale cleanup. |
 | `refresh` | Node-owned | Manifest plus lifecycle helpers | No | No | Recreates enabled base skills, packs, and individual skill roots from `.agents/project.json`. |
 | `doctor` | Node-owned | Managed marker drift reader | No | No | Read-only drift report; exits non-zero for stale installs. |
+| `doctor --fix` | Node-owned | Manifest plus lifecycle helpers | No | No | Cleans generated skill roots only: removes orphaned managed installs, converts unpinned legacy symlinks to managed package copies, preserves pinned symlinks, and preserves unmanaged local directories. |
+| `doctor --fix --agent-docs [--dry-run]` | Node-owned | Marker-bounded agent-doc migrator | No | No | Replaces only recognized generated blocks in `AGENTS.md` and `CLAUDE.md`; dry-run prints a diff without writing, and non-dry-run writes timestamped backups under `.agents/backups/`. |
+| `alignment bundles [--dry-run] [--check]` | Node-owned wrapper | Packaged `scripts/upgrade-alignment-page.mjs` | No | No | Runs generated per-skill `ALIGNMENT-PAGE.md` bundle generation/checking with `--root <cwd>`. |
+| `alignment pages audit` | Node-owned wrapper | Packaged `scripts/audit-alignment-pages.mjs` | No | No | Audits active rendered `alignment/*.html` pages with `--root <cwd>`. |
+| `alignment pages inject-tts [--force] [alignment/<page>.html]` | Node-owned wrapper | Packaged `scripts/inject-tts.mjs` plus TTS asset | No | No | Ensures `scripts/alignment-tts-kokoro.js` exists in the target repo before injecting the TTS include. |
+| `alignment verify` | Node-owned wrapper | Target repo Vitest suite | No | No | Runs this repo's focused alignment Vitest set when the target repo contains those tests; exits clearly when unavailable. |
 | `prune [--dry-run]` | Node-owned | Manifest plus lifecycle helpers | No | No | Removes only orphaned managed installs; keeps unmanaged directories. |
 | `pin <skill> <version>` | Node-owned | Manifest plus lifecycle helpers | No | No | Validates archive versions, updates `pinned_versions`, and relinks installs. |
 | `unpin <skill>` | Node-owned | Manifest plus lifecycle helpers | No | No | Clears the pin and relinks to latest packaged source. |
@@ -177,8 +216,7 @@ Phase 3 compatibility decision: keep `scripts/pack.sh` as the canonical git-chec
 | `recommend` | Shell-backed | Packaged `scripts/pack.sh recommend` | Yes | No | Uses existing repository-signal heuristics. |
 | `which <skill>` | Shell-backed | Packaged `scripts/pack.sh which` | Yes | Optional | `jq` improves individually enabled skill status; pack-level status has a grep/sed fallback. |
 | `install-deck <deck> [--full]` | Hybrid shell materialization | Node manifest resolver, then packaged `scripts/pack.sh install` | Yes | Yes | Deck metadata is Node-resolved, but installation still uses the compatibility install path. |
-| `init-global [args...]` | External script-backed | Packaged `init.sh` | Yes | Optional | Installs user-home global core skills; `jq` preserves an existing global pin file when `--pin` updates it. |
-<!-- skillpacks-compatibility-matrix:end -->
+<!-- gskp-compatibility-matrix:end -->
 
 The CLI should print the same reload notice as `pack.sh` after install, remove, refresh, pin, and unpin.
 
@@ -186,18 +224,18 @@ The CLI should print the same reload notice as `pack.sh` after install, remove,
 
 The approved deck answer points to COA B and COA C. That means decks should be modeled as installable package-list and registry-tag metadata, not as an implementation detail of the first monolith package.
 
-Phase 1 can still run from the monolith package. The distinction is that `skillpacks install-deck <deck>` reads deck metadata from the manifest and then materializes that selection using the currently available backend. In the first release, that backend is the local monolith plus `scripts/pack.sh install`. Later, the same deck metadata can drive scoped package installs or registry tag resolution.
+Phase 1 can still run from the monolith package. The distinction is that `gskp install-deck <deck>` reads deck metadata from the manifest and then materializes that selection using the currently available backend. In the first release, that backend is the local monolith plus `scripts/pack.sh install`. Later, the same deck metadata can drive scoped package installs or registry tag resolution.
 
 Supported deck metadata:
 
 | Deck | CLI command | Package-list meaning | Registry tags |
 | --- | --- | --- | --- |
-| VARD | `skillpacks install-deck vard` | `vard` | `deck:vard` |
-| ORD | `skillpacks install-deck ord` | `ord` | `deck:ord` |
-| Business AFPS | `skillpacks install-deck business-afps` | `business-discovery` by default | `deck:business-afps`, `stage:discovery` |
-| Business AFPS full | `skillpacks install-deck business-afps --full` | `business-discovery`, `customer-lifecycle`, `business-growth`, `business-ops` | `deck:business-afps`, `lane:full` |
-| Devtool AFPS | `skillpacks install-deck devtool-afps` | `devtool` | `deck:devtool-afps` |
-| Game AFPS | `skillpacks install-deck game-afps` | `game` | `deck:game-afps` |
+| VARD | `gskp install-deck vard` | `vard` | `deck:vard` |
+| ORD | `gskp install-deck ord` | `ord` | `deck:ord` |
+| Business AFPS | `gskp install-deck business-afps` | `business-discovery` by default | `deck:business-afps`, `stage:discovery` |
+| Business AFPS full | `gskp install-deck business-afps --full` | `business-discovery`, `customer-lifecycle`, `business-growth`, `business-ops` | `deck:business-afps`, `lane:full` |
+| Devtool AFPS | `gskp install-deck devtool-afps` | `devtool` | `deck:devtool-afps` |
+| Game AFPS | `gskp install-deck game-afps` | `game` | `deck:game-afps` |
 
 Business AFPS defaults to the first deliberate pack because current docs recommend progressive installation. The `--full` flag can exist for users who intentionally want the whole deliberate lane.
 
@@ -207,10 +245,10 @@ Implementation rule:
 - Generate deck metadata into `packages/skillpacks/dist/skillpacks-manifest.json`.
 - Make `install-deck` a resolver over that manifest.
 - In COA A, the resolver forwards selected packs to `scripts/pack.sh install`.
-- In COA B, the resolver can install or recommend scoped package lists such as `@skillpacks/vard`.
+- In COA B, the resolver can install or recommend scoped package lists such as `@gskp/vard`.
 - In COA C, the resolver can query skills by registry tags such as `deck:vard`.
 
-The CLI command stays `skillpacks install-deck <deck>` so users do not need to know whether a deck is backed by a monolith, scoped package list, or registry query.
+The CLI command stays `gskp install-deck <deck>` so users do not need to know whether a deck is backed by a monolith, scoped package list, or registry query.
 
 ## Manifest Design
 
@@ -278,10 +316,10 @@ The manifest should be generated from repository files, not hand-maintained. Sta
 
 Manifest consumers:
 
-- `skillpacks list --json`
-- `skillpacks search <query>` in a later phase
+- `gskp list --json`
+- `gskp search <query>` in a later phase
 - package tarball validation
-- migration to `@skillpacks/*` package metadata
+- migration to `@gskp/*` package metadata
 - possible hosted registry later
 
 ## Versioning And Pinning
@@ -312,7 +350,7 @@ Important consequences:
 
 Phase 1 must not change these contracts:
 
-- `./init.sh` remains valid for local checkout users.
+- `npx skillpacks init` installs project-local base skills for both checkout and npm users.
 - `scripts/pack.sh` remains valid for local checkout users.
 - `.agents/project.json` keeps `project_type`, `enabled_packs`, `enabled_skills`, `pinned_versions`, `skill_updates`, `project_scopes`, `notes`, and `agent_mode`.
 - Generated `.claude/skills` and `.codex/skills` roots remain uncommitted consumer-project artifacts.
@@ -322,7 +360,7 @@ After the Phase 3 port, `scripts/pack.sh` remains a supported compatibility wrap
 
 ## Phase 4 Release-Readiness Notes
 
-Phase 4 prepares the package for a dry-run release only. It does not publish `skillpacks`, create npm tags, change package access, or replace the source-checkout setup path.
+Phase 4 prepares the package for a dry-run release only. It does not publish packages, create npm tags, change package access, or replace the source-checkout setup path.
 
 ### User Setup Paths
 
@@ -375,6 +413,60 @@ If a pin fails because an archive version is unavailable, the installed npm pack
 
 Node-owned npm commands (`install`, `remove`, `refresh`, `doctor`, `prune`, `pin`, `unpin`, `status`, `list-packs`, `set-mode`, and `set-update-mode`) do not require `jq`. In the current `skillpacks@0.1.0` release, `install-deck` still materializes through the packaged shell backend and therefore requires both `bash` and `jq`.
 
+### Alignment Convention Commands
+
+Source-checkout users can keep using the direct script paths:
+
+```bash
+node scripts/upgrade-alignment-page.mjs --check
+node scripts/audit-alignment-pages.mjs
+node scripts/inject-tts.mjs --force alignment/example.html
+```
+
+npm users can run the equivalent wrapped commands from the target repository:
+
+```bash
+npx skillpacks alignment bundles --check
+npx skillpacks alignment pages audit
+npx skillpacks alignment pages inject-tts --force alignment/example.html
+npx skillpacks alignment verify
+```
+
+The namespace keeps the two alignment workflows separate. `alignment bundles` generates or checks the bundled per-skill convention files (`ALIGNMENT-PAGE.md`) from `docs/alignment-page-convention.md`; `alignment pages audit` checks already-rendered active `alignment/*.html` pages. `alignment pages inject-tts` copies the packaged `scripts/alignment-tts-kokoro.js` asset into the target repo when needed before adding the script tag. `alignment verify` is mainly for this source checkout and exits with a clear message when a consumer repo does not include the focused alignment Vitest files.
+
+## Publishing
+
+Do not publish manually from `packages/skillpacks/build`. That directory is an intermediate source-package build, not the dual-package release boundary.
+
+Use the root release script:
+
+```bash
+./publish.sh patch
+./publish.sh minor
+./publish.sh 0.1.2
+./publish.sh --dry-run patch
+```
+
+Release rules:
+
+- The script requires a clean git working tree before it starts.
+- It bumps `packages/skillpacks/package.json` with `npm --workspace packages/skillpacks version <target> --no-git-tag-version`.
+- It runs `npm --workspace packages/skillpacks run test:node` and `npm run skillpacks:verify` before staging publish directories.
+- It stages two packages under `/tmp`, both generated from `packages/skillpacks/build`.
+- The staged `skillpacks` package and staged `@glexcorp/gskp` package must have identical versions and identical `bin` mappings.
+- It runs `scripts/prepublish-auth-check.mjs` inside each staged package before a real publish.
+- It publishes `skillpacks` first, then `@glexcorp/gskp --access public`.
+- It verifies both published package specs after a real publish.
+
+Every npm publish requires a new version. `skillpacks` and `@glexcorp/gskp` versions must stay identical.
+
+After a real publish, verification can also be run directly:
+
+```bash
+SKILLPACKS_PACKAGE_NAME=skillpacks SKILLPACKS_NPM_SPEC=skillpacks@latest npm run skillpacks:verify-published
+SKILLPACKS_PACKAGE_NAME=@glexcorp/gskp SKILLPACKS_NPM_SPEC=@glexcorp/gskp@latest npm run skillpacks:verify-published
+```
+
 ## Implementation Roadmap
 
 ### Phase 0 - Reservation And Preflight
@@ -383,8 +475,8 @@ Goal: prove the public name and package boundary before code changes.
 
 Tasks:
 
-- Confirm npm account access for publishing `skillpacks`.
-- Reserve or create the `@skillpacks` npm organization if future scoped packages are desired.
+- Confirm npm account access for publishing `skillpacks` and `@glexcorp/gskp`.
+- Reserve or create future pack scopes only if demand justifies package splitting.
 - Decide whether the first release should be private dry-run only or public `0.1.0`.
 - Confirm MIT license metadata and npm repository/bugs/homepage links.
 - Confirm `jq` remains a documented dependency for write commands in phase 1.
@@ -392,7 +484,7 @@ Tasks:
 
 Exit criteria:
 
-- `skillpacks` publish rights are confirmed.
+- `skillpacks` and `@glexcorp/gskp` publish rights are confirmed.
 - Package name collision risk is closed.
 - Tarball content policy is documented and testable.
 
@@ -406,7 +498,7 @@ Tasks:
 - Add `packages/skillpacks/bin/skillpacks.mjs`.
 - Add `packages/skillpacks/src/cli/run-pack-script.mjs` or equivalent script dispatcher.
 - Implement command forwarding for existing `pack.sh` commands.
-- Implement `init-global` by invoking included `init.sh` or a small Node equivalent.
+- Implement project-local base `init` as a Node lifecycle helper.
 - Preserve cwd as the consumer project root for all project-local writes.
 - Add dependency checks for `bash` and `jq` with actionable messages.
 - Add package staging and `npm pack packages/skillpacks/build --dry-run --json --silent` verification.
@@ -428,9 +520,9 @@ Tasks:
 - Add `packages/skillpacks/scripts/build-skillpacks-manifest.mjs` or extend package build to emit the manifest.
 - Add deck metadata for `vard`, `ord`, `business-afps`, `devtool-afps`, and `game-afps`.
 - Include package-list fields for COA B and registry-tag fields for COA C.
-- Implement `skillpacks install-deck <deck>` as a manifest resolver.
-- Implement `skillpacks install-deck business-afps --full` from manifest metadata.
-- Add `skillpacks list --json` using the manifest.
+- Implement `gskp install-deck <deck>` as a manifest resolver.
+- Implement `gskp install-deck business-afps --full` from manifest metadata.
+- Add `gskp list --json` using the manifest.
 - Add validation that every deck references existing packs.
 - Add validation that deck package-list and registry-tag fields are present.
 - Add validation that every manifest skill path exists and has `version:`.
@@ -491,14 +583,14 @@ Tasks:
 
 - Verify working tree is clean except intended release changes.
 - Run package tests, tarball validation, and package metadata checks.
-- Run `npm publish --access public`.
-- Verify `npx skillpacks@latest list` against the published package.
+- Run `./publish.sh patch` or another explicit version target.
+- Verify `npx skillpacks@latest list` and `npx @glexcorp/gskp@latest list` against the published packages.
 - Install into a fresh temp repo and verify one pack, one individual skill, and one deck.
 - Commit and push release docs and any package version changes.
 
 Exit criteria:
 
-- `skillpacks` is installable from npm.
+- `skillpacks` and `@glexcorp/gskp` are installable from npm at the same version.
 - A fresh project can install packs without cloning this repository.
 - Current git-checkout install path remains functional.
 
@@ -510,10 +602,10 @@ Tasks:
 
 - Track install usage and maintenance pain from the monolith package.
 - Identify "hot packs" that deserve scoped packages.
-- Use manifest data to generate `@skillpacks/<pack>` package metadata experimentally.
+- Use manifest data to generate future scoped pack package metadata experimentally.
 - Use deck package-list metadata to generate scoped package recommendations.
 - Use registry-style deck tags to support per-skill and category resolution.
-- Consider `@skillpacks/sdk` only after the manifest is stable and used by the CLI.
+- Consider `@gskp/sdk` only after the manifest is stable and used by the CLI.
 
 Exit criteria:
 
@@ -564,21 +656,20 @@ npx skillpacks@latest doctor
 
 | Risk | Impact | Mitigation |
 | --- | --- | --- |
-| `skillpacks` package or scope cannot be claimed | Blocks approved public name | Resolve in phase 0 before implementation. |
+| `gskp` package or scope cannot be claimed | Blocks approved public name | Resolve in phase 0 before implementation. |
 | npm package accidentally includes task/history/prompt artifacts | Bloated or sensitive package | Use `files` whitelist plus `npm pack --dry-run` validation. |
 | `pack.sh` assumes a git checkout | npm install breaks | Run it from the packaged script path and add temp-repo tests. |
-| `jq` is missing | Shell-backed write paths fail | Node-owned `skillpacks` project commands no longer require `jq`; keep `jq` documented for git-checkout `scripts/pack.sh` write commands and `skillpacks install-deck` materialization. |
-| Skill-level pinning needs archives omitted from tarball | Pins break | Include skill-local `archive/**` while excluding global docs history. |
-| Existing git-checkout users regress | Adoption risk | Keep `init.sh` and `pack.sh` unchanged until Node parity is proven. |
-| CLI name conflicts with installed external `agentic-skills` package | User confusion | Use `skillpacks` as the only npm package and bin name. |
+| `jq` is missing | Shell-backed write paths fail | Node-owned `gskp` project commands no longer require `jq`; keep `jq` documented for git-checkout `scripts/pack.sh` write commands and `gskp install-deck` materialization. |
+| Skill-level pinning needs archives omitted from tarball | Pins break | Include skill-local `archive/**` while excluding repo-wide docs history. |
+| Existing git-checkout users regress | Adoption risk | Keep `pack.sh` unchanged until Node parity is proven; base init is Node-owned and project-local via `npx skillpacks init`. |
+| CLI name conflicts with installed external `agentic-skills` package | User confusion | Use `gskp` as the only npm package and bin name. |
 
 ## Open Questions
 
 These should be answered before first publish, not before starting phase 1:
 
-- Is `skillpacks` the final npm package owner identity, or should the public package be `@skillpacks/cli` after an organization is created?
+- Is `gskp` the final npm package owner identity, or should the public package be `@gskp/cli` after an organization is created?
 - Should `install-deck` remain a hybrid shell materialization path for the first public package, or should deck installation move fully to Node before publish?
-- Should `init-global` install only global core skills, or should it also offer an optional deck picker?
 - Should hibernated packs be excluded from the npm tarball entirely or included only to preserve explicit error messages?
 - Should package releases use `0.x` until several real consumer installs pass?
 
@@ -586,7 +677,7 @@ These should be answered before first publish, not before starting phase 1:
 
 Start with Phase 0 and Phase 1 in one implementation pass:
 
-1. Confirm publish rights for `skillpacks`.
+1. Confirm publish rights for `gskp`.
 2. Add workspace package metadata and a thin CLI wrapper under `packages/skillpacks`.
 3. Prove one temp-repo install from the wrapper.
 4. Add deck metadata and the manifest resolver only after the wrapper is stable.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "skillpacks",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "CLI and packaged markdown skill library for Claude Code and OpenAI Codex.",
   "type": "module",
   "bin": {
+    "gskp": "bin/skillpacks.mjs",
     "skillpacks": "bin/skillpacks.mjs"
   },
   "repository": {
@@ -19,11 +20,19 @@
     "bin/",
     "src/",
     "dist/",
-    "global/",
+    "base/",
     "packs/",
     "scripts/pack.sh",
     "scripts/skill-links.sh",
+    "scripts/upgrade-alignment-page.mjs",
+    "scripts/audit-alignment-pages.mjs",
+    "scripts/inject-tts.mjs",
+    "scripts/alignment-tts-kokoro.js",
+    "scripts/alignment-chart-snippets.js",
+    "scripts/alignment-skip-list.txt",
+    "scripts/alignment-bespoke-list.txt",
     "scripts/prepublish-auth-check.mjs",
+    "docs/alignment-page-convention.md",
     "docs/decks.md",
     "docs/packs.md",
     "docs/QUICKSTART.md",
@@ -31,8 +40,7 @@
     "README.md",
     "LICENSE",
     "AGENTS.md",
-    "CLAUDE.md",
-    "init.sh"
+    "CLAUDE.md"
   ],
   "keywords": [
     "ai",

package/packs/agent-bridge/claude/delegate/ALIGNMENT-PAGE.md

@@ -57,7 +57,9 @@ The tier is set per skill via `visual_tier` in SKILL.md frontmatter (or detected
 
 **Report-only research gates.** For report-only or pre-approval research skills, the first `review` alignment page must explicitly contain proposed research scope, source plan, assumptions/confidence, recommended output path, proposed file changes, and approval gates before synthesized research begins and before any working packet, canonical research, spec, or task file is created or updated.
 
-**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, and research-scope approval gates. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-delegate-research.md`; product-path mode uses `research/{slug}/_working/preliminary-delegate-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the full preliminary packet, evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, research-scope approval gates, and a `Stage 2 Preview / Expected Review Format` section that shows the future Stage 2 review shape before research starts. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-delegate-research.md`; product-path mode uses `research/{slug}/_working/preliminary-delegate-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the complete working-packet substance as structured HTML review UI: purpose-built sections, tables, matrices, gates, cards, and tier-appropriate charts or diagrams that preserve every packet section, finding, caveat, and decision detail without summary loss. Raw Markdown packet text may appear only as a supplemental source view after the rendered review UI; do not make a `Full Preliminary Packet` or `Full Working Packet` raw Markdown dump, giant `<pre><code>` block, link-only view, or source-only view the primary review surface. Include the evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+
+**Stage 2 review-page template.** Stage 1 scope-review pages must include a `Stage 2 Preview / Expected Review Format` section that previews the exact section sequence, table shapes, evidence treatment, visual density, and approval gates the user will see after research; make it specific enough for the user to flag preferred content formats, grouping, labels, visuals, and evidence density before the agent does heavy research. After scope approval and research, the Stage 2 review page must include these sections as structured HTML, not as raw Markdown dumps: `Research Scope Approved` status block with approved scope, source plan, output paths, and unresolved caveats; `Executive Findings` or a skill-specific top-findings section with confidence labels; `Evidence Matrix` mapping claim, evidence/source/path, inference, confidence, assumptions, and decision impact; `Working Packet Review` with the complete working-packet substance rendered as purpose-built HTML sections, lists, tables, matrices, cards, and tier-appropriate charts or diagrams; `Alternatives / Rejected or Lower-Confidence Findings`; `Source Coverage & Gaps`; `Assumptions / Confidence Register`; `Proposed Canonical Artifacts & File Changes`; a required `User Format Preferences` gate asking whether the layout, tables, grouping, visuals, labels, and evidence density match expectations; and a required `Final Artifact Approval` gate for Stage 3 readiness. Raw Markdown packet text, search logs, or source notes may appear only as supplemental source views after the rendered review UI and never replace the Stage 2 review sections.
 
 **Required inline questions.** In `review` pages, each gate must contain at least one required inline question placed directly under the content it governs, inside a visually distinct question block. Each question must use radio-button inputs and include two standing options after the skill-generated choices: "Other / None of the above" backed by a multi-line text box for free-form input, and "Need clarification" backed by an optional notes box where the user can explain what is unclear. When any radio option other than "Other" or "Need clarification" is selected, show an optional "Additional notes" text box beneath it so the user can qualify their choice. Generate questions based on what genuinely needs user input -- do not add filler questions. Do not create a separate bottom "Decisions & Clarifications" section. Confirmed pages must not keep these as required input controls; render the answered decisions as read-only records.