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

package/README.md

@@ -33,11 +33,16 @@ CLI tokens should be stored in the platform secret store where possible.
 
 ## Current Slice
 
-This document describes the beta.6 CLI 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
 
@@ -69,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>]
@@ -125,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;
@@ -177,10 +221,12 @@ myskills --version
 myskills login
 ```
 
-The expected candidate version is `0.1.0-beta.6`. It includes the beta.5 managed
-update and personal Codex workspace commands plus the dry-run-only work/team
-bootstrap planner. To test repository changes before release, build and run them
-locally:
+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
@@ -275,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
@@ -301,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
@@ -345,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.