Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Changelog

## 0.1.0-alpha.5 — 2026-11-03

- Show the built-in demo as a short onboarding example with readable enabled
states, a clear synthetic-data label, and an executable next capture step.
- Honor `demo --detail` instead of always printing the detailed report. Preserve
the JSON comparison and real snapshot comparison reports.

## 0.1.0-alpha.4 — 2026-11-03

- Recommend the public npm `alpha` installation in the English and Korean
Expand Down
17 changes: 10 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ SkillWhy compares the skills that fresh Codex CLI processes discover. Capture tw

![A 42-second synthetic CLI demo: compare, inspect, preview a selected share, then compare the shares](https://raw.githubusercontent.com/hyscodebase/skillwhy/main/assets/demo.gif)

Actual CLI output from synthetic fixtures, shown as excerpts. [Video](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo.mp4) · [Full transcript](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo-transcript.txt). This demonstrates the workflow; external user outcomes are still being evaluated.
Actual alpha.3 CLI output from synthetic fixtures, shown as excerpts. The current default demo is shorter; `demo --detail` retains the diagnostic report. [Video](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo.mp4) · [Full transcript](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo-transcript.txt). This demonstrates the workflow; external user outcomes are still being evaluated.

## Try the offline demo

Expand All @@ -30,16 +30,19 @@ skillwhy demo
Use the explicit `alpha` tag while prereleases are being evaluated. [GitHub release tarballs](https://github.com/hyscodebase/skillwhy/releases) with SHA-256 checksums remain available. From a checkout, use `npm ci`, then `npm run demo`; replace `skillwhy` below with `node dist/src/cli.js`.

```text
SkillWhy · skill discovery comparison
SYNTHETIC EXAMPLE — NOT A LIVE SCAN
SkillWhy · demo complete
Synthetic example; your project was not scanned.

key:demo:release-review · enabled-changed
true → false [observed]
release-review: enabled → disabled

Model selected/read/executed a skill: NOT OBSERVED
Existing Desktop session: NOT ASSESSED
1 difference between two sample snapshots.
Scope: discovery metadata. No model or Desktop session was inspected.
```

This is the built-in example, not a capture of your environment. The command also
prints the next capture step. Use `demo --detail` for the full evidence notes or
`demo --json` for the structured comparison.

## Capture and compare

```sh
Expand Down
7 changes: 6 additions & 1 deletion docs/README.ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ Codex CLI를 새로 실행해 발견 목록을 수집하고 두 환경을 비교

![합성 데이터로 보여주는 42초 CLI 데모](https://raw.githubusercontent.com/hyscodebase/skillwhy/main/assets/demo.gif)

실제 CLI 출력의 일부를 사용한 합성 예시입니다. [영상](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo.mp4)과 [전체 출력 기록](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo-transcript.txt)도 제공합니다.
alpha.3 CLI 출력의 일부를 사용한 합성 예시입니다. 현재 기본 demo는 더 짧고,
`demo --detail`로 상세 보고서를 볼 수 있습니다. [영상](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo.mp4)과 [전체 출력 기록](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo-transcript.txt)도 제공합니다.

Node.js 22 이상이 있다면 한 줄로 데모를 실행할 수 있습니다.

Expand All @@ -26,6 +27,10 @@ skillwhy demo
데모는 합성 데이터이며 API 키와 Codex 설치가 필요하지 않습니다.
실제 수집은 검증된 Codex/OS 조합만 지원합니다.

기본 demo는 예제 Skill의 `enabled → disabled` 차이와 실제 수집을 시작하는
명령을 보여줍니다. 내 환경을 검사한 결과는 아닙니다. 긴 근거 설명은
`demo --detail`, 구조화된 결과는 `demo --json`으로 확인할 수 있습니다.

핵심 명령은 `demo`, `capture`, `inspect`, `diff`, `share`입니다.
사용법은 [영문 README](../README.md), 지원 범위는
[호환성 문서](compatibility.md)를 참고하세요.
Expand Down
11 changes: 6 additions & 5 deletions docs/npm-publishing.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,9 @@ before the clean-install checks above.

## Distribution tags

Use the explicit `alpha` tag or an exact prerelease version. After the initial
publication npm also assigned `latest` to alpha.3. An authenticated attempt to
remove that tag returned HTTP 400, so it still points to alpha.3; alpha.4 is
available through `@alpha` and `@0.1.0-alpha.4`. The package has no stable release.
This tag state does not change the verified alpha.4 artifact or its provenance.
Use the explicit `alpha` tag or an exact prerelease version. At the alpha.4
publication, npm's initial `latest` tag still pointed to alpha.3 after an
authenticated removal returned HTTP 400. The `alpha` tag moves with subsequent
prereleases; check `npm view @hyscodebase/skillwhy dist-tags` for its current target.
Exact versions such as `@0.1.0-alpha.4` retain their original artifacts and
provenance. The package has no stable release.
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@hyscodebase/skillwhy",
"version": "0.1.0-alpha.4",
"version": "0.1.0-alpha.5",
"description": "Compare the skills your Codex CLI environments actually discover.",
"type": "module",
"license": "MIT",
Expand Down
4 changes: 2 additions & 2 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import { compareSnapshots } from "./compare.js";
import { createShareBundle } from "./share.js";
import { readSnapshot, writeSnapshot } from "./io.js";
import { demoSnapshots } from "./demo.js";
import { display, renderCapture, renderComparison } from "./report.js";
import { display, renderCapture, renderComparison, renderDemo } from "./report.js";
import { inspectSnapshot, renderInspection } from "./inspect.js";
import { VERSION } from "./version.js";

Expand Down Expand Up @@ -68,7 +68,7 @@ async function main(): Promise<number> {
if (command === "demo") {
const [left, right] = demoSnapshots();
const comparison = compareSnapshots(left, right);
console.log(values.json ? JSON.stringify(comparison, null, 2) : renderComparison(comparison, true));
console.log(values.json ? JSON.stringify(comparison, null, 2) : renderDemo(comparison, values.detail ?? false));
return comparison.status === "complete" ? 0 : 2;
}
if (command === "capture") {
Expand Down
24 changes: 24 additions & 0 deletions src/report.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,30 @@ export function display(value: unknown): string {
return String(value ?? "unknown").replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, " ");
}

/** Keep the built-in onboarding example separate from real diagnostic reports. */
export function renderDemo(result: Comparison, detail = false): string {
const next = [
"Next: run this from your own project with a supported Codex CLI:",
" npx --yes @hyscodebase/skillwhy@alpha capture --cwd . --out before.snapshot.json",
];
if (detail || !result.synthetic) return [renderComparison(result, detail), "", ...next].join("\n");
const lines = [
`SkillWhy · demo ${result.status}`,
"Synthetic example; your project was not scanned.",
"",
];
for (const difference of result.differences) {
const label = display(difference.key.replace(/^key:demo:/, ""));
const value = (input: unknown): string => difference.kind === "enabled-changed" && typeof input === "boolean"
? input ? "enabled" : "disabled" : display(input);
lines.push(`${label}: ${value(difference.before)} → ${value(difference.after)}`);
}
lines.push("", `${result.differences.length} difference${result.differences.length === 1 ? "" : "s"} between two sample snapshots.`,
"Scope: discovery metadata. No model or Desktop session was inspected.",
"", ...next, "", "Full explanation: npx --yes @hyscodebase/skillwhy@alpha demo --detail");
return lines.join("\n");
}

export function renderComparison(result: Comparison, detail = false): string {
const lines = [
"SkillWhy · skill discovery comparison",
Expand Down
14 changes: 12 additions & 2 deletions test/cli.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,18 @@ test("offline demo is explicitly synthetic and detects the disabled entry", asyn
assert.equal(value.synthetic, true);
assert.ok(value.differences.some((d: { kind: string }) => d.kind === "enabled-changed"));
const human = await run(["demo"]);
assert.match(human.stdout, /SYNTHETIC EXAMPLE/);
assert.match(human.stdout, /NOT OBSERVED/);
assert.equal(human.code, 0, human.stderr);
assert.match(human.stdout, /Synthetic example; your project was not scanned/);
assert.match(human.stdout, /release-review: enabled → disabled/);
assert.match(human.stdout, /No model or Desktop session was inspected/);
assert.match(human.stdout, /npx --yes @hyscodebase\/skillwhy@alpha capture --cwd \./);
assert.doesNotMatch(human.stdout, /NOT OBSERVED|NOT ASSESSED|Note:/);
const detailed = await run(["demo", "--detail"]);
assert.equal(detailed.code, 0, detailed.stderr);
assert.match(detailed.stdout, /SYNTHETIC EXAMPLE/);
assert.match(detailed.stdout, /NOT OBSERVED/);
assert.match(detailed.stdout, /Note:/);
assert.deepEqual(JSON.parse((await run(["demo", "--json", "--detail"])).stdout), value);
});

test("bad arguments consistently fail with exit 2", async () => {
Expand Down
Loading