docs: add source-first quickstart

README.md

@@ -5,14 +5,22 @@
 > **Alpha · v0.1.1 · Node.js 20+**
 > SkillSync performs offline checks of local Skill content. It does not execute Skill scripts, does not read credentials, and does not enable live provider, remote-worker, or runtime capabilities.
 
-[![Terminal demo](https://raw.githubusercontent.com/Chumaniac/skillsync/main/docs/assets/verify-demo.png)](https://github.com/Chumaniac/skillsync/blob/main/docs/assets/verify-demo.png)
+[![Terminal demo](https://raw.githubusercontent.com/Chumaniac/skillsync/main/docs/assets/verify-demo.svg)](https://github.com/Chumaniac/skillsync/blob/main/docs/assets/verify-demo.svg)
 
-Run this from a directory containing `SKILL.md`:
+## Run it from source
+
+The npm package publish for `0.1.1` is currently paused. Clone this repository to run the current Alpha build:
 
 ```bash
-npx --yes --package=@chumanic/skillsync@0.1.1 --call 'skillsync verify --path . --target codex'
+git clone https://github.com/Chumaniac/skillsync.git
+cd skillsync
+npm ci
+npm run build
+node dist/cli/index.js verify --path fixtures/product/trust-loop/review --target codex
 ```
 
+The command above verifies the included sample Skill. Replace the fixture path with a directory containing your own `SKILL.md` when you are ready.
+
 ## What you get
 
 - `verify` reviews one local Skill for provenance, target compatibility, and changes without running its scripts.

tests/docs/documentation.test.ts

@@ -40,22 +40,33 @@ describe("release documentation", () => {
 
     expect(readme).toContain("Verify Agent Skills before you trust them.");
     expect(readme).toContain("Alpha · v0.1.1 · Node.js 20+");
+    expect(readme).toContain("## Run it from source");
+    expect(readme).toContain([
+      "```bash",
+      "git clone https://github.com/Chumaniac/skillsync.git",
+      "cd skillsync",
+      "npm ci",
+      "npm run build",
+      "node dist/cli/index.js verify --path fixtures/product/trust-loop/review --target codex",
+      "```",
+    ].join("\n"));
+    expect(readme).toContain("The npm package publish for `0.1.1` is currently paused.");
+    expect(readme).not.toMatch(/@chumanic\/skillsync@0\.1\.1/);
     expect(readme).toContain(
-      "npx --yes --package=@chumanic/skillsync@0.1.1 --call 'skillsync verify --path . --target codex'",
-    );
-    expect(readme).toContain(
-      "https://raw.githubusercontent.com/Chumaniac/skillsync/main/docs/assets/verify-demo.png",
+      "https://raw.githubusercontent.com/Chumaniac/skillsync/main/docs/assets/verify-demo.svg",
     );
+    expect(terminalDemo).toContain("$ git clone https://github.com/Chumaniac/skillsync.git");
     expect(terminalDemo).toContain(
-      "npx --yes --package=@chumanic/skillsync@0.1.1 --call 'skillsync verify --path . --target codex'",
+      "$ node dist/cli/index.js verify --path fixtures/product/trust-loop/review --target codex",
     );
+    expect(terminalDemo).not.toContain("@chumanic/skillsync@0.1.1");
     expect(readme).toContain("does not execute Skill scripts");
     expect(readme).toContain("does not read credentials");
     expect(readme).not.toContain("## Documentation index");
     expect(readme).not.toContain("## Recommended reading order");
     expect(readme).not.toContain("Local release-candidate validation");
-    expect(existsSync("docs/assets/verify-demo.png")).toBe(true);
-    expect(statSync("docs/assets/verify-demo.png").size).toBeGreaterThan(1_000);
+    expect(existsSync("docs/assets/verify-demo.svg")).toBe(true);
+    expect(statSync("docs/assets/verify-demo.svg").size).toBeGreaterThan(1_000);
     expect(security).toContain("not a security certification");
     expect(security).toContain("reporting.include_local_paths");
     expect(security).toContain("<local-path>");