docs: update docs after first alpha release (#49)

Author: mahyarmlk

README.md

@@ -34,6 +34,36 @@ The current repository proves the core shape:
 
 It is not production-ready yet. The goal right now is to keep the foundation small, inspectable, and hard to fake.
 
+## Install
+
+Intent is available as experimental alpha packages on npm:
+
+```sh
+pnpm add @intent-framework/core@alpha @intent-framework/dom@alpha @intent-framework/router@alpha @intent-framework/testing@alpha
+```
+
+```sh
+npm install @intent-framework/core@alpha @intent-framework/dom@alpha @intent-framework/router@alpha @intent-framework/testing@alpha
+```
+
+```txt
+First public alpha: v0.1.0-alpha.0
+GitHub Release: https://github.com/intent-framework/intent/releases/tag/v0.1.0-alpha.0
+```
+
+Published packages:
+
+| Package | npm |
+|---------|-----|
+| `@intent-framework/core` | Platformless semantic graph and runtime |
+| `@intent-framework/dom` | DOM materializer for screens and router |
+| `@intent-framework/router` | Typed route definitions and navigation |
+| `@intent-framework/testing` | Semantic test harness |
+
+`@intent-framework/server` remains private and unpublished.
+
+This is experimental alpha software. APIs are subject to change. Not recommended for production use.
+
 ## Why Intent exists
 
 Modern app code often scatters product meaning across UI components, route files, data hooks, form handlers, test selectors, and backend endpoints.

docs/MVP-Checkpoint.md

@@ -50,7 +50,7 @@ It now has:
 - Complex nested routing/layouts.
 - Form arrays or complex forms.
 - Styling/theming story.
-- Package publishing flow.
+- Production package publishing flow (first alpha published, need to validate end-to-end).
 
 ## Implemented packages
 
@@ -104,7 +104,7 @@ See also the README [Current limitations](../README.md#current-limitations).
 - No backend persistence yet.
 - No real resource cache policy yet.
 - No DevTools package yet.
-- No package publishing flow yet.
+- Package publishing flow is set up (Changesets + manual publish workflow). First alpha published.
 - Demo side panels use manual DOM.
 - Demo diagnostics panel uses `MutationObserver`.
 - Demo data is in memory only.

docs/Release-Readiness.md

@@ -2,15 +2,17 @@
 
 ## Status
 
-Intent is in early experimental development. No packages have been published to npm. No GitHub Releases have been created.
+Intent's first public alpha has been published.
 
-The repository has five workspace packages under `packages/*`. The four publishable packages are at version `0.1.0-alpha.0`. The private server package remains at `0.1.0`. All use `workspace:*` dependency references. The codebase is functional and validated by CI. Changesets is installed and configured. Release workflows exist for automated version PRs and manual alpha publishing.
+GitHub Release: [v0.1.0-alpha.0](https://github.com/intent-framework/intent/releases/tag/v0.1.0-alpha.0)
 
-Four packages are intended for first-alpha publishing. `packages/server` is a private workspace package for now.
+Four packages are published to npm under the `@intent-framework/*` scope. The server package `@intent-framework/server` remains private and unpublished.
 
-## Intended publishable packages
+Changesets is installed and configured. Release workflows exist for automated version PRs and manual alpha publishing.
 
-The first alpha will publish four packages:
+## Published packages
+
+The following packages are published to npm:
 
 | Package | npm name | Purpose |
 |---|---|---|
@@ -243,48 +245,36 @@ Do not manually create GitHub Releases.
 - [x] Release workflows added:
   - Version Packages PR workflow (push-to-main)
   - Manual Publish Alpha workflow (manual dispatch only)
-- [ ] NPM_TOKEN secret added to GitHub repository secrets
-- [ ] Publish first alpha via manual Publish Alpha workflow
-- [ ] Optionally create a GitHub Release manually after npm publish
-
-## Current blockers
-
-- repository fields: present
-- GitHub repository home: `intent-framework/intent`
-- Changesets: installed and configured
-- Release workflows: version-packages.yml (automated version PRs) and publish-alpha.yml (manual publish) are added
-- Remaining first-alpha blocker: add `NPM_TOKEN` secret, then manually run Publish Alpha
+- [x] NPM_TOKEN secret added to GitHub repository secrets
+- [x] Publish first alpha via manual Publish Alpha workflow
+- [x] GitHub Release v0.1.0-alpha.0 created
 
-## Future server-package decisions
+## Post-release verification
 
-- Server maturity is no longer a first-alpha publishing blocker because server is private
-- When the server API matures, the package can be made public and published as a separate decision
+Published packages:
 
-## Do not do yet
+- `@intent-framework/core@0.1.0-alpha.0`
+- `@intent-framework/dom@0.1.0-alpha.0`
+- `@intent-framework/router@0.1.0-alpha.0`
+- `@intent-framework/testing@0.1.0-alpha.0`
 
-- Do not publish any package to npm until the manual Publish Alpha workflow is triggered.
-- Do not create a GitHub Release yet. The current manual Publish Alpha workflow publishes npm packages only. GitHub Releases are not automated yet.
-- Do not change runtime or public APIs.
-- Do not add new dependencies unless required for a specific task.
+Verified:
 
-## Required secret: NPM_TOKEN
+- npm install smoke test passed
+- `alpha` dist-tag points to `0.1.0-alpha.0`
+- `latest` dist-tag currently points to `0.1.0-alpha.0` because this is the only published version
 
-Before running the Publish Alpha workflow, a GitHub Actions secret must be added:
+When stable releases exist, `latest` should point to stable releases and `alpha` should point to prereleases.
 
-| Secret | Purpose |
-|---|---|
-| `NPM_TOKEN` | npm access token with publish permission for `@intent-framework/*` packages |
+## Server package
 
-The token must:
-- Have **publish** permission for the `@intent-framework` npm organization
-- Be stored as a GitHub Actions secret (not in the repository)
-- Be configured in the `npm` GitHub environment used by the Publish Alpha workflow
+`@intent-framework/server` remains a private workspace package until the server API matures. When the server API matures, the package can be made public and published as a separate decision.
 
-Do not commit the token value to the repository.
+## NPM_TOKEN
 
-### Future improvement: trusted publishing
+`NPM_TOKEN` is required for manual publishing. Prefer environment-scoped GitHub secret under the `npm` environment. Use least privilege.
 
-Migrate npm publishing to trusted publishing / OIDC once the initial package publishing flow is stable.
+Future improvement: migrate npm publishing to trusted publishing / OIDC once the initial package publishing flow is stable.
 
 ## Pack check command