@jarel/myskills 0.1.0-beta.5 → 0.1.0-beta.8

package/README.md

@@ -27,16 +27,22 @@ Responsibilities:
 - support maintainer/admin workflows through role-gated API calls
 - enroll a personal Codex workspace and execute approved updates with an explicit companion command
 - inspect an explicitly selected local Codex profile with a read-only metadata observation or health report
+- create a dry-run-only work/team bootstrap plan from explicit approved roots and skill selectors
 
 CLI tokens should be stored in the platform secret store where possible.
 
 ## Current Slice
 
-This document describes the beta.5 candidate. Use a CLI built from the same
-release as the registry for managed updates and Codex workspace commands. The
-beta.2 visibility compatibility shims remain available for existing clients.
-Source versions and npm publication are separate from hosted deployment; the
-API and web expose their deployed version and commit at `/version.json`.
+This document describes the verified beta.7 CLI. Its GitHub prerelease is
+published, and its dedicated API/CLI acceptance passed. It remains compatible
+with existing hosted registry workflows. Beta.7 is deployed to hosted
+production from the verified candidate and adds local authoring and deterministic
+package creation. Native MCP Skills delivery is documented separately in the MCP
+guide. The beta.2 visibility compatibility shims remain available for existing
+clients. Source versions and npm publication are separate from hosted
+deployment; see [Beta.7 release, publication, and staging evidence](../../docs/BETA7_RELEASE_DELIVERY.md)
+for current status. The API and web expose their deployed version and commit
+at `/version.json`.
 
 ### Beta.3 breaking security changes
 
@@ -68,8 +74,10 @@ Implemented commands:
 ```text
 myskills version
 myskills --version
+myskills init <name> [--output <dir>] [--title <text>] [--summary <text>] [--license <text>] [--json]
 myskills validate --path <file-directory-or-zip>
 myskills scan --path <file-directory-or-zip>
+myskills package --path <directory> --output <file.zip> [--json]
 myskills search [query] [--api-url <url>]
 myskills info <skill-slug> [--api-url <url>]
 myskills login [--api-url <url>] [--method <password|api-key>] [--email <email>]
@@ -82,6 +90,7 @@ myskills config get api-url
 myskills config set api-url <url>
 myskills config reset api-url
 myskills config list
+myskills bootstrap codex --dry-run --profile work --context <file> [--work-source-root <dir>] [--shared-source-root <dir>] --live-root <dir> --include-slug <slug> [--include-slug <slug>] --output <report.json>
 myskills submit --path <file-directory-or-zip> [--api-url <url>] [--token <token>]
 myskills review submissions [--api-url <url>] [--token <token>]
 myskills review bundle <submission-id> [--platform <name>] [--output <file>] [--api-url <url>] [--token <token>]
@@ -123,6 +132,43 @@ myskills token list
 myskills token revoke <token-id>
 ```
 
+`myskills init <name>` creates a minimal private Codex package in a new
+directory. The default output is `./<name>`; use `--output` to select another
+destination under an existing parent directory. The command writes `skill.json` and `SKILL.md` with
+version `0.1.0`, `UNLICENSED`, and the `codex-skill` platform target. It does
+not authenticate, call the network, or overwrite an existing file, directory,
+or symlink. Edit the generated `SKILL.md`, then run `myskills validate --path`
+and `myskills scan --path` before any separate authenticated submission.
+
+`myskills package --path ./my-skill --output ./my-skill.zip` creates a
+deterministic ZIP from one checked snapshot of a local package directory.
+It validates the root manifest, portable paths, and bounded UTF-8 text, then
+blocks credential and other blocking scan findings before creating output.
+Warnings remain visible for review. The output reports the archive SHA-256,
+byte size, and a separate `myskills submit --path ...` command. `--json` returns
+the manifest, scan findings, output path, checksum, size, and next command.
+Packaging does not contact the registry or bypass submission and review.
+
+The output must end in `.zip` and have an existing parent directory outside
+the source tree. Existing files, directories, symlinks, and symlink ancestors
+are refused. All regular source files are included; there is no ignore file.
+Keep credentials and unrelated files outside the source directory. The package
+limits are 500 files, 1 MiB of text, 1,000 filesystem entries, and a 10 MiB
+archive. Binary files,
+symlinks, and special files are rejected. Text bytes, including BOMs and line
+endings, are preserved. Entries use ordinal UTF-8 path order, fixed timestamps
+and permissions, and uncompressed ZIP storage, so source mtimes and locale do
+not change the archive checksum. Empty directories and executable bits are not
+preserved. The archive checksum identifies the ZIP bytes, not the registry's
+package-content digest.
+
+Local authoring requires macOS or Linux. The archive is created with private
+file permissions and exclusive creation; it never overwrites a destination
+that appears during the command. A disk or write failure can leave a partial
+output, which the error asks you to inspect before removal. Work in directories
+owned by your user; this does not isolate writes from a hostile process running
+as the same operating-system user.
+
 The API-backed architecture preview includes the compiled graph, escaped
 Mermaid, and a versioned diagram artifact with a plain-text accessible outline.
 Use `--json` when a caller needs the complete JSON/Mermaid/outline projection;
@@ -165,7 +211,7 @@ Those operations require the server's current-revision, organization-policy,
 membership, exact-release, limit, idempotency, and MFA checks. This CLI does
 not expose a second policy implementation or write command for them.
 
-## Published And Candidate Channels
+## Published CLI And Local Builds
 
 The published beta channel is installed with:
 
@@ -175,9 +221,12 @@ myskills --version
 myskills login
 ```
 
-At the start of beta.5 delivery, npm's beta tag points to beta.4. Do not assume
-it includes these candidate commands. From this repository, build and run the
-candidate without publishing:
+The beta.7 GitHub release and verified CLI assets are published. The npm `beta`
+channel currently resolves to `0.1.0-beta.6` while beta.7 awaits maintainer passkey authentication,
+and hosted production runs beta.7. Beta.7 adds deterministic local package
+authoring and the native MCP delivery work described in the repository release
+notes. To test repository changes before a later npm publication,
+build and run them locally:
 
 ```bash
 npm ci
@@ -214,6 +263,43 @@ discarded.
 
 `config get api-url`, `config set api-url <url>`, `config reset api-url`, and `config list` manage the saved API URL. `doctor` checks the CLI version, Node version, resolved API URL, `/health`, auth status, token-store backend, install-directory writability, and `/v1/capabilities`. If the CLI is pointed at the web app instead of the API, or a newer command is sent to an older server, command errors include concrete next steps and `--json` returns structured error codes.
 
+`bootstrap codex --dry-run` is a work/team-only local planner. It requires an
+explicit `work` context, a normalized HTTPS target origin, stable target
+instance/workspace/actor identifiers, explicit source and target trust
+compartments (`work`, `shared`, or `work+shared` for sources, and `work-team`
+for the target), typed `work` and/or `shared` source roots, a target root, and
+a positive `--include-slug` allowlist. The context must approve the computed
+source-root type/digests and target-root digest. Personal, consumer, public,
+and unclassified sources are rejected, and candidates are never selected by
+implicit inventory discovery. A plan accepts at most eight selected candidates;
+each candidate snapshot accepts at most 1,000 entries and 32 nested directory
+levels. A one-skill work-owned canary is supported.
+
+The context JSON must include `profile: "work"`, `targetOrigin`,
+`instanceId`, one `tenantId` or `workspaceId`, `actorId`, the canonical trust
+compartments, `approvedSourceRoots` entries of `{type, identityDigest}`, and
+`approvedTargetRootIdentityDigest`.
+
+The planner reads selected source and target content without network or
+registry access. It opens each selected tree through a bootstrap-owned secure
+snapshot reader, then hashes, parses, scans, and reports only those held bytes.
+It writes only the explicitly requested new private report (`0600`) under a
+user-controlled private parent. Reserved package manifests remain strict:
+invalid or multiple manifests fail closed, and no metadata is relocated. The
+full report contains the work binding, approved root digests, owning package
+contract identifiers, candidate content identities, execution identities, the
+exact target precondition (`absent` or `present-identical` with its expected
+artifact identity), and private snapshots. Terminal output is a redacted DTO
+with counts and digests; it does not contain paths, candidate names, inventory,
+or private identifiers.
+There is no apply, publishing, adoption, or target-write mode in this command.
+`ready` means that the held snapshot passed deterministic checks only. It is
+not approval to apply. Sensitive configuration and credential paths are
+excluded before content enters the report, and heuristic scan-clean never
+replaces explicit human content review. Any future executor must repeat the
+retained source/target identity check immediately before its first write
+(compare-and-swap) and require that review at that boundary.
+
 `validate`, `scan`, and `submit` read one bounded snapshot of the local package.
 `submit` sends those same validated and scanned text entries for directory and
 ZIP inputs. Authors can inspect and withdraw submissions; maintainers fetch the
@@ -235,6 +321,24 @@ and registry instance ID. Legacy records without that identity are not adopted
 automatically: keep their files as a backup, review the source, and install into
 a new root. A registry change requires a separate root.
 
+New installation and snapshot records declare
+`contentDigestAlgorithm: "sha256-json-ordinal-v1"`; transaction journals use
+`targetContentDigestAlgorithm` for the candidate. This scheme normalizes paths,
+sorts them by JavaScript string ordinal order (UTF-16 code units), then hashes
+the UTF-8 JSON array of `{path, content}` entries with SHA-256. It does not
+depend on the process locale. Readers reject unknown algorithm identifiers.
+
+A missing algorithm field identifies the legacy `localeCompare` scheme.
+The CLI verifies these records with the current process's legacy comparison
+rules. It does not retry with a different algorithm. If a locale change makes
+legacy bytes unverifiable, return to the original verification locale and
+compatible Node/ICU environment before a trusted migration. Preserve the files
+and recovery copies if their identity still cannot be proved. Never add an
+algorithm field to an old hash by hand. After verification, an install or
+update records the held bytes with an ordinal digest in the new journal and
+snapshot; rollback does the same for its verified source snapshot. Untouched
+legacy history and journals retain their original verification rules.
+
 Local package intake, install, export, and rollback support macOS and Linux.
 No-follow payload reads and writes, private staging directories, and drift
 checks protect these operations. They do not isolate the workspace from a
@@ -261,8 +365,13 @@ team-owned execution targets are outside this adapter's beta scope.
 `codex observe --upload` records verified filesystem state. Confirm separately
 that Codex loaded the skill. To process one browser-queued update, supply a
 separate token with `skills:read` and `targets:execute` through `MYSKILLS_TOKEN`
-and run `companion run-once`. This command checks current authorization, consent,
-policy, lease, and exact release identity. It does not start a background daemon.
+and run `companion run-once`. If the workspace has a skill installed with
+`--library-entry`, the token also needs `libraries:read`: the companion rechecks
+that adoption before it changes files. Without it, the operation fails with
+`API_TOKEN_SCOPE_REQUIRED` and a message that names the scope; files are not
+changed. The CLI never widens a token's scopes. This command checks current
+authorization, consent, policy, lease, and exact release identity. It does not
+start a background daemon.
 Browser/device login and additional provider install adapters remain planned.
 
 To change skill visibility, use the canonical `myskills sharing set
@@ -305,3 +414,48 @@ Common scopes:
 - `skills:submit` for author submissions.
 - `review:read` and `review:write` for maintainer review workflows.
 - `architectures:read` for architecture list, detail, preview, and fixture-plan reads.
+- `libraries:read` for library reads and for install, update, and companion runs of library-bound skills.
+- `libraries:write` for library changes.
+
+## Libraries
+
+`myskills libraries help` lists the source, import, review, tracking, subscription
+and adoption commands. Requests use the [Libraries API contract](../../docs/plans/2026-09-26-library-api-contract.md)
+and reviewed JSON files supplied with `--input`. The [Libraries guide](../../docs/LIBRARIES.md)
+contains a complete workflow and scope requirements.
+
+Bind an installation to an adopted version with
+`myskills install <slug> --library-entry <entry-id>`. If the adopted release
+requires user action, read its notes and add `--accept-user-action`. Updates
+resolve that exact recommendation and recheck it before changing files. A
+deleted or inaccessible entry never falls back to the newest registry release.
+Local drift still stops replacement. Use
+`myskills libraries unbind-local <slug> --dir <root>` to detach that local
+binding explicitly while retaining files and rollback history.
+
+`updates` and `update` report each skill separately. If an entry is deleted,
+access is lost, the adopted release is revoked, or the entry has no adoption,
+that skill shows `curation-unavailable` with the reason (`library.state` and
+`library.reason` in `--json`). Its files and binding stay unchanged, other skills
+are still evaluated and updated, and `update` exits 1. `install` fails closed
+with `LIBRARY_CURATION_UNAVAILABLE`. A malformed or mismatched resolution stops
+the command with `LIBRARY_RESOLUTION_INVALID`.
+
+If a library adopts a version older than the installed one, the skill shows
+`library-adopts-older` (`adoption-older-than-installed` in `--json`). MySkills
+never downgrades automatically. When the last rollback snapshot is exactly the
+adopted release, run `myskills rollback <slug>`; otherwise install the adopted
+version into a new root with `--dir <new-root>`. `libraries unbind-local` keeps
+the installed version instead.
+
+`libraries review-bundle <submission-id>` prints only after the SHA-256 of the
+response body matches `x-myskills-artifact-sha256`. The JSON output labels its
+`payload` as `parsed-for-inspection`. Use `--output <new-file>` to keep the
+exact verified bytes; an existing file is never replaced. Supply
+`--artifact-sha256 <digest-from-review-requests>` to also verify the immutable
+artifact requested for review. Without it, verification covers the response
+header only; `expectedDigestVerified` reports this distinction in JSON output.
+
+## Skill improvement
+
+Prepare local skill reviews with `myskills improve`, inspect the report, export a draft, and submit it through normal review. Registry plans pin source/reviewer versions and apply user, team or organization policy. Execution requires the exact local plan digest and explicit cloud consent. See [the feature guide](../../docs/SKILL_IMPROVEMENT.md) for commands, JSON bodies, evaluation suites and current adapter limits. The first runner is Claude Code 2.1.283 or newer. Use an exact model ID and an existing Claude sign-in. Codex improvement execution remains disabled pending its isolation gate; final release verification is recorded in the feature guide.