docs: productionize website for v1

Author: jakemccloskey

.env.example

@@ -0,0 +1,3 @@
+DOCSEARCH_APP_ID=
+DOCSEARCH_API_KEY=
+DOCSEARCH_INDEX_NAME=

.github/workflows/test-deploy.yml

@@ -1,13 +1,13 @@
-name: Test deployment
+name: Validate website
 
 on:
   pull_request:
     branches:
       - main
 
 jobs:
-  test-deploy:
-    name: Test deployment
+  quality:
+    name: Typecheck, lint, and build
     runs-on: ubuntu-latest
 
     steps:
@@ -23,5 +23,37 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Test build website
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Lint docs
+        run: npm run lint:docs
+
+      - name: Spellcheck
+        run: npm run spellcheck
+
+      - name: Build website
         run: npm run build
+
+  smoke:
+    name: Browser smoke and accessibility
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browser
+        run: npx playwright install --with-deps chromium
+
+      - name: Run smoke and accessibility checks
+        run: npm run test:smoke

.gitignore

@@ -11,10 +11,15 @@
 # Misc
 .DS_Store
 .env.local
+.env
 .env.development.local
 .env.test.local
 .env.production.local
 
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+# Test output
+/playwright-report
+/test-results

.markdownlint-cli2.jsonc

@@ -0,0 +1,15 @@
+{
+  "config": {
+    "default": true,
+    "line-length": false,
+    "first-line-heading": false,
+    "no-inline-html": false
+  },
+  "ignores": [
+    "node_modules/**",
+    "build/**",
+    ".docusaurus/**",
+    "playwright-report/**",
+    "test-results/**"
+  ]
+}

README.md

@@ -1,28 +1,66 @@
 # Soundscript Website
 
-This repository uses Docusaurus for both the public marketing page and the developer docs.
+This repository hosts the public Soundscript website with a single Docusaurus stack:
+
+- `/` for the marketing homepage
+- `/docs` for developer-facing documentation
+- future product surfaces like `/playground` as custom pages in the same site
 
 ## Local development
 
 ```bash
 npm install
-npm start
+npm run dev
 ```
 
-## Build
+## Quality checks
 
 ```bash
+npm run typecheck
 npm run build
+npm run lint:docs
+npm run spellcheck
+npm run test:smoke
 ```
 
-## Typecheck
+`test:smoke` builds the site, serves the production output locally, and runs Playwright smoke plus
+accessibility checks.
+
+## Search
+
+The site is wired for Algolia DocSearch through environment variables:
 
 ```bash
-npm run typecheck
+cp .env.example .env.local
 ```
 
-## Structure
+Then set:
+
+- `DOCSEARCH_APP_ID`
+- `DOCSEARCH_API_KEY`
+- `DOCSEARCH_INDEX_NAME`
+
+If those variables are absent, the site still builds and runs, but the DocSearch UI is not shown.
+
+## Docs ownership
+
+The website repo owns:
+
+- homepage content
+- onboarding and adoption docs
+- task-oriented guides
+
+The Soundscript repo remains the canonical source for normative language and tooling references such
+as annotations, diagnostics, builtin contracts, machine numerics, and macro semantics. The website
+mirrors those references with a canonical-source note at the top of each relevant page.
+
+## Versioning
+
+Docs versioning is prepared in the site configuration, but the first frozen version should be cut
+only at the real v1 tag:
+
+```bash
+npm run docs:version:v1
+```
 
-- `/` is the marketing homepage
-- `/docs` is the developer documentation
-- future product surfaces like `/playground` can be added as custom Docusaurus pages
+Run that at the actual `1.0.0` release point, then rebuild and deploy the site.

cspell.config.yaml

@@ -0,0 +1,45 @@
+version: '0.2'
+language: en
+dictionaries:
+  - softwareTerms
+  - html
+  - css
+ignorePaths:
+  - node_modules
+  - build
+  - .docusaurus
+words:
+  - algolia
+  - builtin
+  - builtins
+  - cspell
+  - docsearch
+  - inout
+  - interop
+  - macros
+  - metaprogramming
+  - newtype
+  - newtypes
+  - nullness
+  - numerics
+  - overclaimed
+  - overclaiming
+  - playwright
+  - soundscript
+  - soundness
+  - stdlib
+  - stdio
+  - stringifying
+  - subclassing
+  - sublabel
+  - sublist
+  - thenables
+  - tsconfig
+  - typecheck
+  - typeclasses
+  - unlisted
+  - userland
+  - wasi
+  - wordmark
+  - valueclass
+  - wasm

docs/concepts/runtime-and-builtins.md

@@ -3,6 +3,9 @@ title: Runtime and Builtins
 description: How the v1 runtime story, JS target, and compiler-owned builtin modules fit together.
 ---
 
+Use this page when you want the runtime story that ties together JS output, builtin modules, and
+the conservative v1 deployment model.
+
 The stable v1 runtime story is deliberately conservative.
 
 ## The stable target story
@@ -96,3 +99,9 @@ an ecosystem fork.
 Macro-related builtin surfaces such as `sts:macros` are part of the supported language surface, but
 they still belong later in the docs. They are advanced capabilities, not the default on-ramp for a
 regular TypeScript team.
+
+## See also
+
+- [Tooling and JS Target](../guides/tooling-and-js-target.md)
+- [Builtin Modules](../reference/builtin-modules.md)
+- [Stable v1 Support Matrix](../reference/stable-v1-support-matrix.md)

docs/concepts/soundness-model.md

@@ -3,6 +3,9 @@ title: Soundness Model
 description: What Soundscript is actually claiming, and what it is intentionally not claiming.
 ---
 
+Use this page when you need the conceptual contract behind the language rules, not just a list of
+forbidden constructs.
+
 Soundscript is not trying to prove “all of TypeScript is sound.”
 
 It creates a smaller, explicit contract for `.sts` modules inside the existing JS/TS ecosystem.
@@ -105,3 +108,9 @@ The main practical change is not “more theory.” It is better local reasoning
 - a reviewer can see where trust enters the module
 - a maintainer can tell whether an assumption was checked or only asserted
 - a boundary-heavy module can become meaningfully safer without converting the entire repo
+
+## See also
+
+- [Soundscript vs TypeScript](../getting-started/soundscript-vs-typescript.md)
+- [Interop Boundaries](../guides/interop-boundaries.md)
+- [Banned and Restricted Surface](../reference/banned-and-restricted.md)

docs/getting-started/adopt-in-existing-typescript-apps.md

@@ -0,0 +1,104 @@
+---
+title: Adopt in Existing TypeScript Apps
+slug: /getting-started/adopt-in-existing-typescript-apps
+description: The practical migration path for teams adopting Soundscript inside a working TypeScript application.
+---
+
+Use this page when you are planning a real rollout in an existing TypeScript codebase. The point is
+not to “convert the repo.” The point is to start where stronger guarantees pay for themselves and
+expand only when the new boundary is earning its keep.
+
+## Start with modules that already act like trust boundaries
+
+Good first targets are usually:
+
+- request and queue handlers
+- decoders, parsers, and validation layers
+- auth and permission checks
+- package entrypoints or app service boundaries
+- code that already wraps risky legacy or third-party behavior
+
+Avoid broad utility folders or heavily shared framework glue as your first migration target.
+
+## A practical first week
+
+1. Install `soundscript` locally and run `soundscript init --mode existing`.
+2. Pick one boundary-heavy module and rename it to `.sts`.
+3. Mark every ordinary `.ts`, `.js`, or declaration-only import with `// #[interop]`.
+4. Remove unchecked escapes like `any`, `as`, and non-null assertions.
+5. Normalize foreign throws and make local conditions explicit.
+6. Add `soundscript check` to package scripts and CI.
+
+That is enough to learn the model without turning the adoption into a rewrite project.
+
+## Example migration boundary
+
+```ts title="src/payments/charge.sts"
+// #[interop]
+import {chargeCard} from '../legacy/payments.ts';
+import {normalizeThrown} from 'sts:failures';
+
+export async function runCharge(request: ChargeRequest): Promise<ChargeReceipt> {
+  try {
+    const receipt = await chargeCard(request);
+    if (receipt.status !== 'ok') {
+      throw new Error('Charge failed.');
+    }
+    return receipt;
+  } catch (error) {
+    throw normalizeThrown(error);
+  }
+}
+```
+
+This is a good first migration because:
+
+- the boundary to legacy code is obvious
+- the failure path matters
+- the module already sits on an application seam
+
+## What usually changes first
+
+The first `.sts` modules rarely need advanced features. Most early fixes are just:
+
+- explicit `undefined` and `null` checks
+- replacing assertion-based typing with validation or narrowing
+- local `Error` discipline
+- visible interop boundaries
+
+That is exactly what you want. It means the adoption is paying off before you reach for machine
+numerics, macros, or advanced variance work.
+
+## What not to migrate first
+
+Defer these until the team is comfortable with the basics:
+
+- dense UI glue code
+- broad helper libraries with unclear ownership
+- reflection-heavy adapters
+- low-value leaf utilities with little boundary risk
+- framework internals where the team is still experimenting with architecture
+
+## Signs a module is a bad first target
+
+It is probably not a good first migration if:
+
+- most of the file is framework ceremony
+- the file is shared everywhere but trusted nowhere
+- it relies on metaprogramming or very loose ambient assumptions
+- the team cannot yet explain what the runtime boundary actually is
+
+## When this page matters
+
+Use this guide when you need to:
+
+- choose the first `.sts` modules
+- explain the rollout strategy to the team
+- decide what belongs in the first CI gate
+- keep the adoption scoped and realistic
+
+## See also
+
+- [Quick Start](./quick-start.md)
+- [Soundscript vs TypeScript](./soundscript-vs-typescript.md)
+- [Interop Boundaries](../guides/interop-boundaries.md)

docs/getting-started/adoption-faq.md

@@ -3,6 +3,9 @@ title: Adoption FAQ
 description: Common first-pass questions from TypeScript teams evaluating Soundscript.
 ---
 
+Use this page when you want short answers to the questions that come up in the first evaluation
+conversation.
+
 ## Is Soundscript a different language from TypeScript?
 
 It is a different **checked contract**, not a different parser language.
@@ -109,3 +112,9 @@ It does **not** claim:
 
 The main claim is narrower and more useful: checked code should stay closer to what the runtime
 actually guarantees, and trust boundaries should be explicit.
+
+## See also
+
+- [Quick Start](./quick-start.md)
+- [Soundscript vs TypeScript](./soundscript-vs-typescript.md)
+- [Adopt in Existing TypeScript Apps](./adopt-in-existing-typescript-apps.md)