@skill-map/spec 0.57.0 → 0.58.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Spec changelog
 
+## 0.58.0
+
+### Minor Changes
+
+- Bare `sm` in an empty folder now offers a getting-started menu: on an interactive terminal it asks whether to run the guided tutorial (`sm tutorial`) or drop a ready-to-explore example project (`sm example`), then dispatches the chosen verb. In a non-empty folder, or on a non-interactive stdin, it still prints a one-line hint and exits 2, now pointing at `sm tutorial` / `sm example` when the folder is empty and at `sm init` otherwise.
+
+  ## User-facing
+
+  Run `sm` in an empty folder and it now asks how you want to start: a guided tutorial, or a ready-made example project to explore. Pick one and it sets it up for you.
+
+- New `sm example` verb: drops a ready-to-explore example project (the same wired harness the public demo renders) into an empty directory, so a new user can run `sm scan` then `sm serve` against a real connected graph without authoring files first. The payload is the single canonical `fixtures/demo-scope/` fixture, shared with the web demo, and ships unscanned (no `.skill-map/`). Refuses a non-empty cwd unless `--force`.
+
+  ## User-facing
+
+  New `sm example` command: run it in an empty folder to drop a small ready-made project, then `sm scan` and `sm serve` to explore it as a live graph. The fastest way to try skill-map without setting up your own files first.
+
 ## 0.57.0
 
 ### Minor Changes

package/cli-contract.md

@@ -9,7 +9,9 @@ Normative description of the `sm` CLI surface: verbs, flags, exit codes, machine
 - Primary: `sm`.
 - Long alias: `skill-map`. MUST resolve to the same binary. A symlink, shim, or alias in `bin` field of `package.json` is acceptable.
 - Help invocation: `sm --help` and `sm -h` MUST print top-level help and exit with code 0.
-- Bare invocation: `sm` with no arguments starts the Web UI server (equivalent to `sm serve`) when a `.skill-map/` project is initialized in the cwd. With no project in the cwd, it MUST print a one-line hint to stderr pointing at `sm init` and `sm --help`, then exit `2`.
+- Bare invocation: `sm` with no arguments starts the Web UI server (equivalent to `sm serve`) when a `.skill-map/` project is initialized in the cwd. With no project in the cwd:
+  - When the cwd is empty AND stdin is an interactive terminal, it MUST present a getting-started menu with two choices, run the guided tutorial (equivalent to `sm tutorial`) or drop a ready-to-explore example project (equivalent to `sm example`), and dispatch the chosen verb. The menu reads from stdin and renders to stderr; an empty answer selects the first option (tutorial).
+  - Otherwise (a non-empty cwd, a non-interactive stdin, or no valid choice within the prompt's bounded re-ask), it MUST print a one-line hint to stderr and exit `2`. The hint points at `sm tutorial` / `sm example` when the cwd is empty, or at `sm init` / `sm --help` when it is not.
 
 ---
 
@@ -202,6 +204,21 @@ Flags: `--for <provider-id>` (destination Provider, skips the prompt); `--force`
 
 Exit: `0` on success; `2` if the cwd is not empty and `--force` was not passed; `2` if an unexpected positional argument is passed (the verb takes no positional; e.g. the removed `master` variant, the advanced walkthrough is now a part inside the single skill, reached from its menu); `2` if `--for` names a Provider that does not exist or declares no `scaffold.skillDir`; `2` on any I/O failure.
 
+#### `sm example`
+
+Materialize a ready-to-explore example project (the "harness") directly into the current working directory, so a new user can run `sm scan` and `sm serve` against a real, pre-wired graph without authoring any files first. This is the concrete counterpart to `sm tutorial`: where `sm tutorial` installs the guided walkthrough skill, `sm example` drops the finished scenario the walkthrough builds toward, a small portfolio handbook (`AGENTS.md`) that mentions a content-editor agent and invokes a publish command, a `check-links` skill the publish command invokes, and the deploy / style docs they reference. It is the same harness the public demo renders. The verb takes **no positional argument** and no provider flag (the example ships the Claude layout).
+
+Behaviour:
+
+- Writes the example project files directly into the cwd: `AGENTS.md` (plus its `.sm` sidecar), `.claude/agents/`, `.claude/commands/`, `.claude/skills/check-links/`, `docs/`, `public/`, `package.json`, `server.js`, and a `.skillmapignore` / `.gitignore`. The content is the canonical example shipped with the implementation; a conforming implementation MUST embed an equivalent wired scenario (the exact files are informative, what is normative is that the verb produces a scannable project a fresh `sm scan` resolves into a connected graph).
+- Does NOT write `.skill-map/`: the project ships unscanned, so the user's first `sm scan` provisions the project fresh and auto-detects the lens from the on-disk markers.
+- Requires the cwd to be empty (a listing including dotfiles returns nothing), so the user can delete the whole directory afterwards without losing prior work. A non-empty cwd is refused (exit 2) unless `--force` (which proceeds, overwriting any colliding files).
+- Does NOT require an initialized project and never reads or writes project config. A pre-bootstrap helper.
+
+Flags: `--force` (proceed even when the cwd is not empty, overwriting any colliding files, without prompting).
+
+Exit: `0` on success; `2` if the cwd is not empty and `--force` was not passed; `2` if an unexpected positional argument is passed (the verb takes no positional); `2` on any I/O failure (including a missing bundled example payload).
+
 #### `sm version`
 
 Prints version matrix:

package/index.json

@@ -174,14 +174,14 @@
       }
     ]
   },
-  "specPackageVersion": "0.57.0",
+  "specPackageVersion": "0.58.0",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "009253ec6623f1d6932eb0f3e7b1b9b0f0f6c765c9989be1c00818e8db54a216",
+      "CHANGELOG.md": "f8bb4c603a79d734e24091d5dd9f3f90f5e4c7c27266794885227ace2246be9f",
       "README.md": "a790cd010b46d47883d1f37e3893cea9d7aa69ec4750c0202e6a0c99991e7980",
       "architecture.md": "04583ed36a5336d14b27e6fe73368455867fd0856bb4199b489fb471f7edd646",
-      "cli-contract.md": "97dda0c49ef3e3666806dc0b709b248f2fc479cbedab01f407db58309651bbb5",
+      "cli-contract.md": "7c90de3b680e428bff16f0e1991046b6417a3c94851994e1194fa32c33584e45",
       "conformance/README.md": "dcbef7249f161acf597552a05dcadc813cd0ced430dcd3f813fcf5e1c876335d",
       "conformance/cases/backtick-path-extraction.json": "4620e7f8bc161fc57cb44001e9d99879c7e22b4865a0c27a20dc28969cd936d9",
       "conformance/cases/extractor-collision-detection.json": "179a02c61892f0d26492de0c4e2c327fa6b4986d1265a8f119e871df6afe4658",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skill-map/spec",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "JSON Schemas, prose contracts, and conformance suite for the skill-map specification.",
   "license": "MIT",
   "type": "module",