Skip to content

docs(15128): Phase 1 FTUE — TEA leak cleanup + Ink migration guide#8

Open
beorn wants to merge 1 commit into
mainfrom
feat/15128-phase-1-ftue
Open

docs(15128): Phase 1 FTUE — TEA leak cleanup + Ink migration guide#8
beorn wants to merge 1 commit into
mainfrom
feat/15128-phase-1-ftue

Conversation

@beorn
Copy link
Copy Markdown
Owner

@beorn beorn commented May 19, 2026

Phase 1 of the silvery docs reorg (km @km/silvery/15128-docs-reorg).

Goal: Make README → homepage → quick start a seamless 60-second journey. Zero TEA-as-shipped wording. Give Ink users an obvious migration path.

Scope — 9 files

Homepage + packages tables (4 files)

  • `docs/index.md` — Coming bullet: `@silvery/create` → `Silvertea (ships as @silvery/create)`; packages table: mark `@silvery/create` `(coming soon)`.
  • `README.md` — packages table + Coming bullet: same treatment.
  • `docs/about.md` — packages table: same treatment.
  • `docs/reference/packages.md` — Power-User Imports block: drop `createSlice/createStore` example; add `::: tip Coming soon` for `@silvery/create`.

Drop-in Ink migration guide (1 new file)

  • `docs/getting-started/migrate-from-ink.md` — drop-in story at top (`bun remove ink && bun add silvery react` + `from "ink"` → `from "silvery/ink"`). 918/931 Ink 7.0 tests pass. Walks through what's the same, what's different (13 intentional design choices), what you can opt into later. Refers into the existing `silvery-vs-ink` deep-dive.

Replace unshipped `createApp()` examples (2 files)

  • `docs/guide/find.md` — replace `pipe(createApp(store), withFocus(), …)` activation example with shipped `render().run()`; add Coming Soon note for Silvertea composability.
  • `docs/guide/scope.md` — 3 `createApp(store)` examples replaced with shipped `render().use(withScope("app")).run()`. Silvertea `pipe()` form kept as explicit "Coming soon" code blocks so the design narrative isn't lost.

Gate state-management.md (2 files)

  • `docs/guides/state-management.md` — prominent `::: danger` banner at top declaring Silvertea unshipped; points readers at `useState` / `useReducer` / Zustand for today.
  • `docs/.vitepress/config.ts` — remove "State Management" from sidebar + nav; add "Migrate from Ink" under Getting Started in both.

Verification

  • `bun run docs:build` — succeeds. `migrate-from-ink.html` builds. The 10 pre-existing glossary anchor warnings into `/guide/silvery-vs-ink#rendering` etc. are not introduced by this PR.
  • Migration guide appears in the sidebar under Getting Started, right after Quick Start.
  • README + about.md + index.md + reference/packages.md all say "coming soon" on `@silvery/create`.
  • No live `createApp()` examples remain in find.md / scope.md (kept only inside explicitly-labeled Coming Soon blocks).

Reader-facing before/after

Homepage "Coming" section

Before:

  • @silvery/create — structured state management with commands, keybindings, effects-as-data

After:

  • Silvertea — structured state management with commands, keybindings, effects-as-data (ships as `@silvery/create`)

README packages table

Before:

| `@silvery/create` | Composable app builder — `pipe()` providers |

After:

| `@silvery/create` | Composable app builder — `pipe()` providers (coming soon) |

Getting Started sidebar

Before:

Getting Started
Quick Start

After:

Getting Started
Quick Start
Migrate from Ink

Scope: 9 file edits per @km/silvery/15128-docs-reorg/phase-1-ftue.

- Homepage Coming bullet: '@silvery/create' → 'Silvertea (ships as @silvery/create)'
- Packages tables (README, about.md, index.md, reference/packages.md):
  mark @silvery/create as '(coming soon)'
- New getting-started/migrate-from-ink.md: drop-in '@silvery/ink' compat
  story at top, links into existing Ink comparison for deep-dive
- Sidebar + nav: surface 'Migrate from Ink' under Getting Started
- Sidebar: gate 'State Management' (documents Silvertea, not shipped)
- state-management.md: prominent ::: danger Coming Soon banner at top
- find.md: replace 'createApp + pipe' example with shipped 'render().run()'
  + Coming Soon caveat for Silvertea composability
- scope.md: replace 3 'createApp(store)' examples with shipped
  'render(...).use(withScope(...)).run()' + Coming Soon Silvertea notes

Closes nothing on its own — Phase 1 of a 4-phase docs reorg.
Parent: @km/silvery/15128-docs-reorg.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant