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
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# Changelog

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

- Recommend the public npm `alpha` installation in the English and Korean
quickstarts after an isolated registry install and demo passed for alpha.3.
- Record the initial package's integrity against the compiled GitHub release,
and document npm's publish-time availability delay and OIDC validation gate.
- Include reviewed GitHub Actions updates in this release. Native capture
support and comparison behavior are unchanged from alpha.3.

## 0.1.0-alpha.3 — 2026-11-02

- Add specific next steps for unsupported, partial, and failed captures and
Expand Down
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,22 +12,22 @@ Actual CLI output from synthetic fixtures, shown as excerpts. [Video](https://gi

## Try the offline demo

Requires Node.js 22 or later and Git:
Requires Node.js 22 or later:

```sh
npx --yes github:hyscodebase/skillwhy#v0.1.0-alpha.3 demo
npx --yes @hyscodebase/skillwhy@alpha demo
```

The first run downloads and builds the tagged source. The demo uses synthetic snapshots. It needs no Codex installation, API key, or model call.
The first run downloads the compiled [npm package](https://www.npmjs.com/package/@hyscodebase/skillwhy). The demo uses synthetic snapshots. It needs no Codex installation, API key, or model call.

To install the compiled GitHub release once and use the shorter `skillwhy` command:
To install once and use the shorter `skillwhy` command:

```sh
npm install --global https://github.com/hyscodebase/skillwhy/releases/download/v0.1.0-alpha.3/hyscodebase-skillwhy-0.1.0-alpha.3.tgz
npm install --global @hyscodebase/skillwhy@alpha
skillwhy demo
```

This is a GitHub release, not an npm registry publication. Release assets include a SHA-256 checksum. From a checkout, use `npm ci`, then `npm run demo`; replace `skillwhy` below with `node dist/src/cli.js`.
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
Expand Down Expand Up @@ -101,7 +101,7 @@ No runtime dependencies. Tests use synthetic records and local fake subprocesses

Try the [10-minute pilot](docs/pilot.md) to report installation friction or a useful support case. External pilot outcomes have not yet been established.

For incomplete results, see [troubleshooting](docs/troubleshooting.md). Maintainers can use the [interview guide](docs/interviews.md) and [weekly metrics](docs/metrics.md) to track feedback. Registry publication is being prepared separately; [npm distribution](docs/npm-publishing.md) records its current status.
For incomplete results, see [troubleshooting](docs/troubleshooting.md). Maintainers can use the [interview guide](docs/interviews.md) and [weekly metrics](docs/metrics.md) to track feedback. [npm distribution](docs/npm-publishing.md) records publication and clean-install evidence.

[Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [한국어](docs/README.ko.md) · [Roadmap](docs/roadmap.md)

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

실제 CLI 출력의 일부를 사용한 합성 예시입니다. [영상](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo.mp4)과 [전체 출력 기록](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo-transcript.txt)도 제공합니다.

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

```sh
npx --yes github:hyscodebase/skillwhy#v0.1.0-alpha.3 demo
npx --yes @hyscodebase/skillwhy@alpha demo
```

처음에는 해당 태그의 소스와 빌드 의존성을 다운로드합니다.
처음에는 빌드된 [npm 패키지](https://www.npmjs.com/package/@hyscodebase/skillwhy)를 다운로드합니다.
빌드된 패키지를 한 번 설치하고 짧은 명령으로 사용하려면:

```sh
npm install --global https://github.com/hyscodebase/skillwhy/releases/download/v0.1.0-alpha.3/hyscodebase-skillwhy-0.1.0-alpha.3.tgz
npm install --global @hyscodebase/skillwhy@alpha
skillwhy demo
```

초기 버전을 사용하려면 `alpha` 태그를 명시하세요. SHA-256 체크섬이 포함된
[GitHub 릴리스 파일](https://github.com/hyscodebase/skillwhy/releases)도 제공합니다.
데모는 합성 데이터이며 API 키와 Codex 설치가 필요하지 않습니다.
실제 수집은 검증된 Codex/OS 조합만 지원합니다.

Expand Down Expand Up @@ -55,7 +57,7 @@ Desktop 채팅의 상태도 검사하지 않습니다. 공유 파일은 한 항
1,000스타는 도전 목표이며 제품의 성능이나 성공을 보장하는 수치가 아닙니다.

실제 실행 검증은 [검증 기록](validation.md), 다음 버전 발행과 지원 범위 확대 절차는
[릴리스 가이드](releasing.md)를 참고하세요. GitHub에서 패키지를 배포하며 npm 레지스트리에는 아직 게시하지 않았습니다.
[릴리스 가이드](releasing.md)를 참고하세요. npm 공개 레지스트리와 GitHub에서 패키지를 배포합니다.

첫 사용 경험과 실제 도움 여부를 확인할 [10분 파일럿 안내](pilot.md)와 피드백 양식도 제공합니다.
외부 사용자의 파일럿 결과와 반복 사용은 아직 검증되지 않았습니다.
Expand Down
6 changes: 3 additions & 3 deletions docs/execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,16 @@ Preparing materials is not equivalent to completing an external validation gate.
| 1. Maintainer problem interviews | Five candidate projects researched; bilingual questions and invitation drafts prepared | Five actual interviews and two recurring, relevant problems |
| 2. External pilots | Self-serve guide and report form available | Three external attempts; at least two useful comparisons without author assistance |
| 3. Correct repeated pilot friction | Engineering review added explicit next steps for unsupported, partial, and unassociated results | Two repeated pilot blockers corrected and rechecked by participants |
| 4. npm distribution | Public alpha metadata and an optional packaging/publication workflow prepared | Namespace owner authenticates, first package publishes, clean registry install passes; then trusted publisher setup |
| 4. npm distribution | Alpha.3 published publicly; isolated registry install and npx demo passed with matching release integrity; exact GitHub Trusted Publisher configured | First successful OIDC publication and clean install of that release |
| 5. Broader native compatibility | Ubuntu 24.04 x64 candidate and production checks passed on Node 22/24; macOS production checks pass | Complete for the newly admitted Codex 0.166.0/Linux x64 tuple; other combinations remain outside the evidence |
| 6. Two useful external cases | Interview and evidence-register formats prepared | Two participant-confirmed, approved public accounts of help with an actual problem |
| 7. Demonstration and README | 42-second GIF/MP4 and transcript published; public assets were fetched and matched their local hashes | Complete for the synthetic demonstration; actual user cases remain task 6 |
| 8. Maintenance automation | Shared CI and actionlint passed on the default branch; weekly dependency scans completed | Complete for the configured maintenance checks |
| 9. Targeted introduction and weekly evidence | Two channel drafts prepared; first hosted public-aggregate report succeeded | Approved account-based publication and response handling |

The initial external interview, completed-pilot, and approved-case registers are
empty. npm authentication was unavailable during preparation. These are pending
dependencies, not successful outcomes. Keep [the interview record](interviews.md),
empty. npm publication and an isolated registry install were verified on
2026-11-03; external participants remain pending. Keep [the interview record](interviews.md),
[outreach record](outreach.md), [npm status](npm-publishing.md), and
[native compatibility evidence](compatibility.md) aligned as evidence arrives.

Expand Down
40 changes: 29 additions & 11 deletions docs/npm-publishing.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# npm distribution

Registry publication is pending. GitHub release tarballs remain the currently
available installation route. The `alpha` npm dist-tag below becomes usable only
after the first successful registry publication.
The public [npm package](https://www.npmjs.com/package/@hyscodebase/skillwhy) is
available. The initial `0.1.0-alpha.3` publication and an isolated public registry
installation were verified on 2026-11-03; see [the validation record](validation.md#public-npm-installation).
Use `npx --yes @hyscodebase/skillwhy@alpha demo` for the offline demo.

The package is prepared as `@hyscodebase/skillwhy`, with public access, an `alpha`
dist-tag, and `https://registry.npmjs.org` in its publication metadata. Confirm
that the npm account owns this namespace before the first publication.
The package is published as `@hyscodebase/skillwhy`, with public access, an `alpha`
dist-tag, and `https://registry.npmjs.org` in its publication metadata. The namespace owner performed the initial interactive publication.

## First publication
## Initial publication procedure

1. Authenticate interactively with `npm login --registry=https://registry.npmjs.org`.
Complete npm's account verification in your own browser. Credentials and
Expand All @@ -29,14 +29,15 @@ describes namespace ownership, public visibility, and account verification.

## Subsequent releases from GitHub Actions

Configure the package's npm Trusted Publisher with:
The package's npm Trusted Publisher is configured with:

| Field | Value |
| --- | --- |
| Organization or user | `hyscodebase` |
| Repository | `skillwhy` |
| Workflow filename | `npm-publish.yml` |
| Allowed action | Direct `npm publish` |
| Allowed action | Direct `npm publish` (and npm's implicit `npm stage publish`) |
| Environment name | None |

The manual **npm distribution** workflow accepts an existing prerelease tag on
`main`. Its default `publish: false` runs tag validation, the shared CI matrix,
Expand All @@ -45,8 +46,9 @@ No registry version is created in that mode. To publish after account setup,
dispatch from that exact tag with `publish: true`, for example:

```sh
gh workflow run npm-publish.yml --ref v0.1.0-alpha.3 \
-f release_tag=v0.1.0-alpha.3 -F publish=true
RELEASE_TAG=vX.Y.Z-alpha.N # Replace with the next unpublished prerelease.
gh workflow run npm-publish.yml --ref "$RELEASE_TAG" \
-f release_tag="$RELEASE_TAG" -F publish=true
```

Real publication requires both the dispatch ref and event commit to match the
Expand All @@ -62,3 +64,19 @@ workflow uses Node 24 and checks the required npm CLI version. Follow the
[official Trusted Publishing instructions](https://docs.npmjs.com/trusted-publishers/)
when configuring the package; a successful dry run does not prove npm publishing
authorization is configured.

A newly created connection must complete its first successful publication within
2 days. The connection was saved on 2026-11-03; its first real OIDC publication is
still pending. Do not treat saving the form or a dry run as successful registry
authorization. Once a version is published, use a new version and tag for the
next attempt that changes package contents; do not replace published versions.

## Availability after publication

npm can accept a publication before the version becomes installable. Its
[publish-time scanning announcement](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/)
describes a typical delay of a few minutes, which can take longer. An immediate
404 after a successful publish is not evidence that the version can be safely
republished. Check the existing version and its integrity again before any retry.
The initial alpha.3 request returned HTTP 202 and became publicly installable
before the clean-install checks above.
6 changes: 3 additions & 3 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ SkillWhy's release workflow builds a downloadable npm tarball and `SHA256SUMS` o

1. Change the version in `package.json` and both version fields in `package-lock.json`. `src/version.ts` reads the installed package metadata, so there is no second CLI version constant to update.
2. Update the changelog and compatibility evidence. Run `npm ci`, `npm test`, and `npm run typecheck`. `npm test` includes the release gate and publication state tests.
3. Merge the release commit into `main`. Wait for the normal branch CI, then tag that exact commit, for example `git tag -a v0.1.0-alpha.3 -m 'SkillWhy 0.1.0-alpha.2'` and `git push origin v0.1.0-alpha.3`.
3. Merge the release commit into `main`. Wait for the normal branch CI, then tag that exact commit, for example `git tag -a v0.1.0-alpha.4 -m 'SkillWhy 0.1.0-alpha.4'` and `git push origin v0.1.0-alpha.4`.
4. Watch **GitHub prerelease** in Actions. The release becomes public only after workflow lint, all four Linux/macOS × Node 22/24 jobs, and the packaged installation smoke checks pass.

Tag pushes matching `v*` trigger the workflow. The tag must equal `v` plus the package version, point to the checked out/event commit, and already be an ancestor of `origin/main`. Annotated and lightweight tags both work. Only prerelease versions such as `0.1.0-alpha.2` are accepted; stable versions and build metadata are deliberately rejected until a stable-release policy is added. A prerelease is never marked as the repository's latest stable release.
Expand Down Expand Up @@ -35,15 +35,15 @@ npm ci
RELEASE_DIR="$(mktemp -d)/assets" node scripts/release-build.mjs
```

The command prints a manifest of the two assets. It installs only into a temporary prefix and does not publish anything. `RELEASE_DIR` must not already exist; keeping old artifacts in place causes a failure instead of silently reusing them. The temporary installed prefix is removed; the requested output directory remains for inspection. Version/tag ancestry is checked separately by `RELEASE_TAG=v0.1.0-alpha.3 node scripts/release-check.mjs` after creating the tag.
The command prints a manifest of the two assets. It installs only into a temporary prefix and does not publish anything. `RELEASE_DIR` must not already exist; keeping old artifacts in place causes a failure instead of silently reusing them. The temporary installed prefix is removed; the requested output directory remains for inspection. Version/tag ancestry is checked separately by `RELEASE_TAG=v0.1.0-alpha.4 node scripts/release-check.mjs` after creating the tag.

## Install a release asset

Download the `.tgz` file and `SHA256SUMS` from the same GitHub prerelease. In their directory, verify the checksum before installation:

```sh
shasum -a 256 -c SHA256SUMS
npm install --prefix ./skillwhy-install --ignore-scripts --no-audit --no-fund ./hyscodebase-skillwhy-0.1.0-alpha.3.tgz
npm install --prefix ./skillwhy-install --ignore-scripts --no-audit --no-fund ./hyscodebase-skillwhy-0.1.0-alpha.4.tgz
./skillwhy-install/node_modules/.bin/skillwhy --version
./skillwhy-install/node_modules/.bin/skillwhy demo
```
Expand Down
17 changes: 16 additions & 1 deletion docs/validation.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,23 @@
# Alpha validation record

Date: 2026-11-02. These observations are scoped engineering checks, not a claim
Updated: 2026-11-03. These observations are scoped engineering checks, not a claim
of production readiness, adoption, or model accuracy.

## Public npm installation

On 2026-11-03, `@hyscodebase/skillwhy@0.1.0-alpha.3` became available from the
public npm registry. Its registry SHA-1 and SHA-512 integrity matched the compiled
GitHub release tarball; that file's SHA-256 is
`7e87ba34b8da5fca027cd5eb54e7aa796b27ec536e19f9eb4cdcd8f8221a3fcd`.

An installation into a new temporary prefix, with a new cache and empty user and
global npm configuration, reported `0.1.0-alpha.3` and ran `demo --json` with
`status: complete`. An isolated `npm exec --package=@hyscodebase/skillwhy@alpha`
demo produced the same JSON. These checks used Node 24.8.0 and npm 11.11.0 on
macOS arm64, with no registry login available to the installation process.
This establishes public package distribution and the offline demo, rather than
additional native Codex compatibility or external adoption.

## Alpha.3 native support investigation

After extracting the production compatibility manifest, the existing macOS arm64
Expand Down
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.3",
"version": "0.1.0-alpha.4",
"description": "Compare the skills your Codex CLI environments actually discover.",
"type": "module",
"license": "MIT",
Expand Down
Loading