silvermoon 0.0.3 → 0.1.1

package/docs/getting-started.md

@@ -9,23 +9,28 @@ This guide is the authoritative setup and first-use path for Silvermoon.
 - Permission to fetch that branch and to publish ordinary non-force commits
   through the repository's normal collaboration path.
 
-## Install The Project Dependency
+## Run Silvermoon And Register Its Skill
 
-Install Silvermoon in the repository so every collaborator uses the declared
-version:
+Install Silvermoon independently of the target project's dependency graph, or
+invoke a chosen version temporarily:
 
 ```sh
-npm install --save-dev silvermoon
+npm install --global silvermoon
+silvermoon whats-next
+# or: npx silvermoon@<version> whats-next
 ```
 
-Register the canonical packaged skill through the supported `skills` interface:
+The setup report gives the exact path for the running installation. Use it to
+register the bundled canonical skill through the universal `skills` target:
 
 ```sh
-npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent github-copilot --yes --copy
+npx skills add <path-to-running-silvermoon>/skills --skill silvermoon --agent universal --yes --copy
 ```
 
-Silvermoon diagnoses whether the project dependency, installed package, and
-repository-local skill match. It does not install dependencies or mutate skill
+The registration lives only at `.agents/skills/silvermoon`. Silvermoon checks
+that its content exactly matches the running installation. It does not require
+the target repository to use Node, contain `package.json`, declare a
+Silvermoon dependency, or have `node_modules`, and it never mutates skill
 registration itself.
 
 ## Configure The Shared Primary
@@ -43,10 +48,10 @@ The repository URL is credential-free, canonical shared state. Credentials,
 named remotes, and URL rewrites remain local Git concerns. Silvermoon metadata
 paths are fixed and cannot be overridden by configuration.
 
-## Configure Preferred Language
+## Configure Content And Output Language
 
 All language values are canonical BCP 47 tags such as `en` or `zh-CN`.
-Silvermoon resolves natural-language output in this order:
+Silvermoon resolves the language for project-owned content in this order:
 
 1. optional idea `status.yaml` `language`;
 2. optional project `.silvermoon/config.yaml` `preferredLanguage`;
@@ -62,45 +67,82 @@ preferredLanguage: zh-CN
 
 Inherited values remain dynamic and are not copied into an idea. Use
 `create-idea --language <tag>` only when the new idea needs a stable override.
-`whats-next` reports both the effective tag and its source.
+That command continues to accept any canonical BCP 47 tag.
+
+For one invocation's Silvermoon-owned output, `whats-next` and `check` accept
+only the built-in `en-US` and `zh-CN` locales. Input casing is normalized, so
+`EN-us` and `zh-cn` are accepted. This override has higher display precedence
+than idea, project, or user content language and is never persisted:
+
+```sh
+silvermoon whats-next <idea> --language zh-CN
+silvermoon check --worktree --language en-US
+```
+
+Every observation reports the actual built-in locale as `outputLanguage`.
+When configuration is available, `configuration.preferredLanguage` remains
+the resolved content language and can therefore differ from `outputLanguage`.
+Without a temporary override, Chinese content tags use `zh-CN` output and all
+other content tags use the built-in `en-US` output.
 
 ## Create The First Idea
 
 Run:
 
 ```sh
-npx silvermoon create-idea --json
-npx silvermoon create-idea --language zh-cn --json
+silvermoon create-idea
+silvermoon create-idea --language zh-cn
 ```
 
-The command first applies the same repository, worktree, conflict, and ancestry
-hygiene used by navigation. When those checks pass, it creates one untracked
-idea scaffold with `Idea.md`, `Implementation.md`, `Deployment.md`,
-`ledger.md`, and `status.yaml`. It never stages, commits, pushes, or records a
-human decision.
-
-Replace the guidance in `Idea.md` with the desired outcome, scope, and
-constraints. Keep implementation and deployment placeholders synchronized
-until their lifecycle phases. Review every generated path and publish the
-prepared idea through ordinary Git.
+The command requires the configured primary branch and upstream plus a clean
+local worktree. It does not fetch or require local HEAD to match the remote
+tip. When those checks pass, it creates one untracked idea scaffold with
+`Idea.md`, `Implementation.md`, `Deployment.md`, `ledger.md`, and
+`status.yaml`. It never stages, commits, pushes, or records a human decision.
+
+Replace the guidance in the `Idea.md` ideal contract with the desired outcome,
+scope, and constraints. Keep the `Implementation.md` inner implementation
+contract and `Deployment.md` real-world deployment contract placeholders
+synchronized until their lifecycle phases. Review every generated path,
+validate the complete candidate, and commit and publish the prepared idea to
+the configured primary through the repository's normal non-force publication
+path. Verify it is reachable from refreshed primary before asking the user to
+review or approve the exact reported ideal revision. If publication requires a
+pull request, wait until it reaches primary; never ask for approval of an
+unpublished local candidate. Publication does not itself approve the idea.
 
 Then ask what comes next with the generated ULID or an exact unique alias:
 
 ```sh
-npx silvermoon whats-next <idea> --json
+silvermoon whats-next <idea>
 ```
 
-The report contains one highest-priority action. Execute only that action. Run
-the same command again only after an expected repository change, an unexpected
-input change, or a newly arrived external result.
+The default dialogue uses lightweight Markdown headings for intent,
+observation, and ordered next instructions; actions and outcomes appear only
+when an operation was attempted. Add `--json` only when a programmatic
+consumer needs the `intention / observation / outcomes / instructions`
+envelope. Execute the applicable instructions in order and run the same
+command again only after an expected repository change, an unexpected input
+change, or a newly arrived external result.
 
 ## Make Decisions Explicit
 
 Silvermoon never infers approval or acceptance. After a person explicitly
 approves the current ideal, accepts the current implementation, or accepts the
 current deployment, record the exact revision reported by `whats-next` in the
-corresponding `status.yaml` field. Validate the full candidate, stage it,
-validate the staged snapshot, and publish a normal non-force commit.
+corresponding `status.yaml` field. Validate the full candidate with
+`silvermoon check --worktree`, stage it, then run `silvermoon check --staged`
+to validate the index before publishing a normal non-force commit. Default
+`check` validates committed `HEAD`, not the pending commit; only a successful
+project validation exits `0`.
+
+When requesting any approval or acceptance, include the idea's alias and ULID,
+the decision and exact world revision, plus a clickable permalink to the
+canonical world entry pinned to the published primary commit. Link to
+`Idea.md`, `Implementation.md`, or `Deployment.md` as appropriate. Do not use
+a local workspace path or a branch-floating link; if the host has no known
+permalink format, provide the primary commit and repository-relative path and
+explain the limitation.
 
 Continue with [Core Concepts](./core-concepts.md) before changing lifecycle
 contracts, or use [Operating Silvermoon](./operations.md) for the routine

package/docs/maintaining.md

@@ -14,7 +14,8 @@ pnpm install --frozen-lockfile
 Use the smallest check that covers a change:
 
 ```sh
-pnpm sync:skills       # refresh the generated GitHub Copilot skill copy
+pnpm sync:skills       # refresh the generated universal skill copy
+pnpm lint:markdown     # Markdown lint and link checks
 pnpm test              # fast unit and repository contract tests
 pnpm test:integration  # real filesystem and Git behavior
 pnpm test:e2e          # packed and installed CLI behavior
@@ -22,10 +23,18 @@ pnpm check             # complete release-grade validation
 pnpm check:skills      # skill discovery and structure
 ```
 
+`pnpm check` runs the independent release-grade checks concurrently and waits
+for all of them before reporting every failure. Run the narrower commands above
+while iterating, then use `pnpm check` before delivery.
+
 Edit the canonical skill only under `skills/silvermoon`, then run
-`pnpm sync:skills`. The checked-in `.github/skills/silvermoon` directory is a
+`pnpm sync:skills`. The checked-in `.agents/skills/silvermoon` directory is a
 generated copy so repository skill discovery works without symbolic-link
 support. `pnpm check:skills` rejects a stale or manually edited copy.
+The repository-only publish skill is maintained directly under
+`.agents/skills/publish`; it is not part of the generated copy or npm package.
+For documentation and skill changes, run `pnpm lint:markdown`,
+`pnpm check:skills`, and `node --test test/contract/skill.test.mjs`.
 
 Run `pnpm check` after CLI, schema, repository model, release, or skill changes.
 Documentation work must also preserve Markdown links, package contents,
@@ -53,4 +62,7 @@ Use [npm package releases](./npm-package-releases.md) for trusted publishing,
 tag rules, release validation, and failure recovery. Publishing occurs only
 through `.github/workflows/publish-npm.yml` from an immutable
 `npm/silvermoon/v<version>` tag whose commit is reachable from `origin/main`.
-Never publish locally or add an npm token.
+The workflow generates both package READMEs in an isolated staging tree,
+validates and publishes one tarball, then checks its registry integrity,
+package-level README, provenance, and commit-pinned jsDelivr assets. Never
+publish locally or add an npm token.

package/docs/npm-package-releases.md

@@ -92,13 +92,24 @@ The [`publish-npm.yml`](../.github/workflows/publish-npm.yml) workflow then:
 1. verifies the tagged commit is reachable from refreshed `origin/main`;
 2. installs the frozen pnpm dependencies;
 3. runs the allowlisted release planner and confirms the version is absent
-   from npm;
+   from npm, or records that an exact-version rerun must skip publication;
 4. runs `pnpm test:unit`, `pnpm test:contract`, `pnpm test:integration`, and
    `pnpm check:skills`;
-5. runs the selected package's `npm run pack:check` and
-   `npm run test:e2e`; and
-6. publishes only the selected directory with provenance and the derived npm
-   dist-tag.
+5. creates an isolated `git archive` staging tree and generates commit-pinned
+   English and Chinese package READMEs without changing the tagged checkout;
+6. creates one tarball, records its path, SHA-256, npm shasum, registry
+   integrity, and complete file list, then passes that same file to
+   `npm run pack:check` and `npm run test:e2e`;
+7. publishes that exact tarball with provenance and the derived npm dist-tag
+   when the version was absent; and
+8. runs `verify-npm-release.mjs` until the registry is consistent or the
+   bounded retry window expires.
+
+The post-publication verifier requires the exact version and dist-tag, registry
+integrity and tarball bytes, package-level README, both tarball READMEs, npm
+publish and SLSA provenance attestations, tagged Git commit, and commit-pinned
+jsDelivr SVG responses to match the candidate. A successful run prints
+`VERIFY_NPM_RELEASE_OK` with the verified identities.
 
 Release runs are serialized within this repository. The registry preflight and
 `npm publish` cannot form one cross-system transaction, so an external
@@ -110,13 +121,20 @@ duplicate publication without replacing the existing version.
 Publication stops before `npm publish` when the tag is malformed, the release
 key is unknown, the package is private, the package name or version differs
 from the mapping and tag, the npm publish configuration is not public npmjs,
-the commit is outside `origin/main`, the version already exists, registry state
-cannot be verified, or validation fails.
+the commit is outside `origin/main`, registry state cannot be observed, or
+validation fails. If the exact version already exists during a workflow rerun,
+the publish step is skipped and the verifier must prove that registry content
+is byte-identical to the rebuilt candidate and carries the expected provenance.
+Any mismatch is a hard failure.
 
 For a transient GitHub or registry failure before publication, rerun the same
 workflow run. Do not move or recreate the tag. For a source, manifest, or
 validation failure, make a new commit on `main`, choose a new version, and push
 a new tag after the fix is merged. npm versions and release tags are immutable.
+For a transient verification failure after publication, rerun only the failed
+workflow job when GitHub offers that option; the planner recognizes the
+existing version, skips `npm publish`, and performs the same complete
+verification again.
 
 ## Add another package
 

package/docs/operations.md

@@ -9,64 +9,91 @@ publishing Silvermoon ideas.
 npx silvermoon whats-next
 npx silvermoon whats-next 01M36QGPNTXEPP61DA4KP4AVZF
 npx silvermoon whats-next publish-documentation --json
+npx silvermoon whats-next publish-documentation --language zh-CN
 ```
 
 Without a selector, Silvermoon asks for a choice among multiple active ideas,
-continues a single active idea, or reports that a new idea can be created. A
-selector is either a canonical uppercase ULID or an exact, unique,
-case-sensitive alias.
-
-Each successful report includes the effective `language` tag and its `idea`,
-`project`, `global`, or `default` source. Its action guidance requires the
-Agent to use that language for world entries, same-world supporting artifacts,
-the ledger, and user-facing explanations. Commands, identifiers, schema fields,
-protocol markers, and verbatim tool output retain their original form.
-
-Every invocation first checks the configured primary branch, merge conflicts,
-worktree changes, and local/remote primary ancestry. It may fetch and inspect,
-but it never edits, checks out, merges, commits, stashes, deletes, resets,
-fast-forwards, or pushes.
+and the option to discuss and create a new idea. This remains true with zero,
+one, or many active ideas: only a selector chooses work. Completed and abandoned
+ideas are excluded from default candidates. A selector is either a canonical
+uppercase ULID or an exact, unique, case-sensitive alias.
+
+The shared observation exposes the resolved content preference as
+`configuration.preferredLanguage` and the built-in rendering locale as
+`outputLanguage`. Instructions use the content preference for world entries,
+same-world supporting artifacts, and the ledger. A caller may use
+`--language en-US|zh-CN` to override only Silvermoon-owned output for one
+`whats-next` invocation. Commands, identifiers, schema fields, protocol
+markers, and verbatim tool output retain their original form.
+
+Every invocation follows three strict layers. It first checks Git,
+configuration compatibility, and `.agents/skills/silvermoon`. It then checks
+local conflicts, changes, HEAD, and upstream identity before any remote access.
+Only after those checks pass does it fetch primary, compare ancestry, and
+route idea work. It never edits, checks out, merges, commits, stashes, deletes,
+resets, fast-forwards, or pushes.
 
 ## Create An Idea
 
 Explicit creation uses:
 
 ```sh
-npx silvermoon create-idea --json
-npx silvermoon create-idea --language zh-cn --json
+silvermoon create-idea
+silvermoon create-idea --language zh-cn
 ```
 
 Creation intent is distinct from active-idea selection. If hygiene blocks the
 command, perform only the reported remediation and retry `create-idea`; do not
 replace the request with selector-less navigation.
 
-`--language` is the only command-level language override. It normalizes a valid
-BCP 47 tag and writes it to the new idea's `status.yaml`. Without the option,
-creation writes no language field and the idea dynamically inherits project,
-user, or `en-US` defaults. `whats-next` and `check` do not accept the option.
+Creation checks project readiness, then requires the configured primary branch
+and upstream plus a clean worktree. It does not fetch, compare ancestry, or
+require local HEAD to be aligned with the remote tip. Its preparation reports
+omit the active-idea inventory because existing work does not replace explicit
+creation intent.
+
+For `create-idea`, `--language` normalizes any valid BCP 47 tag and writes it
+to the new idea's `status.yaml` as a persistent content-language preference.
+Without the option, creation writes no language field and the idea dynamically
+inherits project, user, or `en-US` defaults. This is distinct from the
+non-persistent `en-US|zh-CN` output override accepted by `whats-next` and
+`check`.
 
 The generated files remain untracked for review. Complete `Idea.md`, optionally
 add a concise unique alias, inspect every path, and publish the initial idea
-through ordinary Git.
-
-## Execute One Action
-
-Treat the command, request, `observedPrimaryCommit`, selected idea, and action
-as one immutable observation. Execute only the highest-priority action.
-
-Repository hygiene actions take precedence over lifecycle work. Inspect exact
-staged, unstaged, untracked, and conflicted paths; preserve unknown and
-concurrent work. Never force-push, use `reset --hard`, broadly clean the
-worktree, or silently rewrite history to satisfy guidance.
+through ordinary Git. Validate and commit the complete prepared idea, then make
+that commit reachable from configured primary using the repository's normal
+non-force publication path before asking the user to review or approve it. If
+publication requires a pull request, wait until it reaches primary. Reobserve
+the exact `idealRevision` after publication; never ask for approval of an
+unpublished local candidate, and never treat publication as approval.
+
+## Follow One Observation
+
+Treat `intention`, `observation`, `outcomes`, and `instructions` as one
+immutable dialogue report for `whats-next` and `create-idea`. Default output
+uses lightweight Markdown headings and lists for intent, observation, and
+next instructions, including actions and outcomes only if an operation was
+attempted. `--json` serializes the same model, retaining `outcomes: []` when
+none were attempted.
+
+Project setup takes precedence over repository synchronization, which takes
+precedence over lifecycle work. Instructions include every known remediation
+for the current layer in priority order. Large change sets report complete
+counts, bounded path samples, omitted counts, and exact commands for the full
+diff. Preserve unknown and concurrent work. Never force-push, use
+`reset --hard`, broadly clean the worktree, or silently rewrite history.
 
 After an observable change, run `whats-next` again. Do not poll an unchanged
-observation.
+observation. When the invocation used `--language`, every generated retry
+command preserves the same canonical output-language option.
 
 ## Author World Contracts
 
-`Idea.md` is the Ideal World entry. `Implementation.md` and `Deployment.md`
-contain `## Steps` and `## Acceptance criteria`. Every item uses a stable
-level-three heading:
+`Idea.md` is the Ideal World's ideal contract. `Implementation.md` is the
+Inner World's inner implementation contract, and `Deployment.md` is the Outer
+World's real-world deployment contract. The latter two contain `## Steps` and
+`## Acceptance criteria`. Every item uses a stable level-three heading:
 
 - implementation steps: `I-Sxx`
 - implementation criteria: `I-ACxx`
@@ -94,14 +121,46 @@ the current reported world revision. Edit only the corresponding status fact:
 Validate the complete candidate:
 
 ```sh
-npx silvermoon check --worktree --json
+silvermoon check --worktree
+silvermoon check --worktree --language zh-CN
 git add .silvermoon/ideas/<ULID>/status.yaml
-npx silvermoon check --staged --json
+silvermoon check --staged
 ```
 
+`check` is a project-only validator, not a navigation command. It does not
+check worktree hygiene, upstream, or ancestry and does not suggest next steps.
+Without a target it validates committed `HEAD`, not the pending commit.
+`--worktree` validates the full candidate, while `--staged` validates exactly
+the index and is the pre-commit hook target. Its JSON has `intention` and
+`observation` only; it has no `outcomes` or `instructions`. Exit status `0`
+means the chosen project snapshot is valid; `1` means invalid or unavailable
+and must block the commit; `2` means invalid CLI usage. Do not treat the
+existence of a report as permission to commit.
+
+`check --language en-US|zh-CN` changes only Silvermoon-owned report framing.
+It is orthogonal to every check target and never changes the selected snapshot,
+validation conclusion, problems, or exit status.
+
+`check` does not infer that a status field was newly written, prove who
+authorized it, compare it with a commit parent, or search history for its
+origin. Those are workflow responsibilities: match an explicit human decision
+to the exact revision reported by `whats-next`, edit only the corresponding
+status fact, review the candidate, and publish without rewriting concurrent
+history. Old decision revisions may remain in status after a world changes;
+their mismatch is what derives the idea's earlier lifecycle state.
+
 Prefer a status-only decision commit, publish through the repository's normal
 non-force path, and verify the commit is reachable from refreshed primary.
 
+When asking for approval or acceptance, identify the idea by alias and ULID,
+state the exact reported world revision, and link the corresponding canonical
+entry at the published primary commit: `Idea.md` for ideal approval,
+`Implementation.md` for implementation acceptance, or `Deployment.md` for
+deployment acceptance. Use a commit-pinned web permalink rather than a local
+workspace path or a branch name that can move. The linked revision and
+publication are review context only; the user must still make the decision
+explicitly.
+
 ## Publish Work
 
 Before publication, compare with the observed primary tip, run checks focused