Restructure repo and overhaul documentation (VitePress docs site)

.gitignore

@@ -3,3 +3,5 @@ dist/
 node_modules/
 coverage.out
 pocketstack-demo/
+docs/.vitepress/dist/
+docs/.vitepress/cache/

.goreleaser.yaml

@@ -38,11 +38,11 @@ archives:
       - SECURITY.md
       - CONTRIBUTING.md
       - CODE_OF_CONDUCT.md
-      - docs/*.md
+      - docs/**/*.md
       - docs/media/*
       - examples/**/*
-      - site/*
-      - studio/*
+      - web/site/*
+      - web/studio/*
 
 checksum:
   name_template: "checksums.txt"

CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to PocketStack are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
 follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-Per-release detail lives in [docs/RELEASE_NOTES_v*.md](docs/).
+Per-release detail lives under [docs/release-notes/](docs/release-notes/index.md).
 
 ## [1.1.0] - 2026-06-28
 
@@ -48,14 +48,14 @@ Per-release detail lives in [docs/RELEASE_NOTES_v*.md](docs/).
 Refocused the product around browser-native readiness: `analyze` reports a
 readiness score, blockers, suggestions, and next steps; clearer primary
 unsupported reasons; conversion guide. See
-[release notes](docs/RELEASE_NOTES_v1.0.3.md).
+[release notes](docs/release-notes/v1.0.3.md).
 
 ## [1.0.2] - 2026-05-27
 Hosted Studio, generated example demos, and the GitHub Pages site. See
-[release notes](docs/RELEASE_NOTES_v1.0.2.md).
+[release notes](docs/release-notes/v1.0.2.md).
 
 ## [1.0.1] - 2026-05-26
-Hardening release. See [release notes](docs/RELEASE_NOTES_v1.0.1.md).
+Hardening release. See [release notes](docs/release-notes/v1.0.1.md).
 
 ## [1.0.0] - 2026-05-26
 Initial browser-native PocketStack release.

CONTRIBUTING.md

@@ -30,13 +30,17 @@ release.
 
 Work on a branch and open a pull request against `main`. Note user-facing
 changes in [CHANGELOG.md](CHANGELOG.md) under an `Unreleased`/next-version
-heading; the [release process](docs/RELEASE.md) covers tagging and publishing.
+heading; the [release process](docs/contribute/releasing.md) covers tagging and
+publishing.
 
 New adapters should add:
 
 - analyzer classification tests;
 - generated manifest coverage;
 - browser runtime tests;
 - an example Compose project;
-- documentation in the compatibility matrix;
+- documentation under [docs/adapters/](docs/adapters/index.md);
 - clear unsupported-feature reporting for nearby cases that still cannot work.
+
+The full developer guide — repo layout, prerequisites, and the new-adapter
+walkthrough — lives at [docs/contribute/](docs/contribute/index.md).

Makefile

@@ -22,7 +22,7 @@ runtime:
 	npm run build:runtime
 
 studio:
-	python3 -m http.server $(PORT) --directory studio
+	python3 -m http.server $(PORT) --directory web/studio
 
 media:
 	npm run media
@@ -42,6 +42,7 @@ smoke: build
 	npm run test:smoke
 
 pages: smoke
+	npm run docs:build
 	npm run pages:build
 
 release-check: test lint smoke release-dry-run verify-checksums

README.md

@@ -1,35 +1,29 @@
 # PocketStack
 
 PocketStack turns browser-compatible Docker Compose projects into shareable
-demos that run as static browser apps.
+demos that run as static browser apps — no hidden server, no runner, and no
+Docker at demo time.
 
-> Drop in `docker-compose.yml`, get a static browser-native demo when every
-> service can be mapped to browser primitives.
+> Drop in a `compose.yaml`, get a static, browser-native demo when every service
+> maps to a browser primitive. When one can't, PocketStack tells you why and how
+> to reshape it — it never fakes a runner.
 
-PocketStack v1 is intentionally browser-native. Generated demos do not start a
-hidden server, upload projects to a runner, require Docker at demo time, or
-pretend arbitrary Linux containers can run in a web page. If a service cannot
-be represented honestly by a browser adapter, PocketStack gives you a
-readiness report and concrete conversion suggestions.
-
-Try it now: <https://ramazankara.github.io/pocketstack/>
+**[Try it now](https://ramazankara.github.io/pocketstack/)** ·
+**[Documentation](https://ramazankara.github.io/pocketstack/docs/)** ·
+**[Studio](https://ramazankara.github.io/pocketstack/studio/)**
 
 [![PocketStack announcement video](docs/media/pocketstack-announcement-poster.png)](docs/media/pocketstack-announcement.mp4)
 
-## What You Can Demo
-
-PocketStack is useful for projects that have a browser-native shape:
+## What you can demo
 
-- static sites served by `nginx`, `httpd`, or `caddy`;
-- frontend projects that can run with a Node/Bun browser runtime;
-- prebuilt WASI modules;
-- OpenAPI services that can be mocked from specs and fixtures;
-- Postgres-flavored demos that fit PGlite;
-- SQLite demos seeded from SQL or database files.
+Six browser adapters map Compose services to real browser primitives:
+`static-web`, `frontend` (WebContainer), `mock-http` (OpenAPI), `sqlite`,
+`postgres-pglite`, and `wasi`. See the [compatibility matrix](docs/adapters/index.md).
 
-It is not a Docker replacement. Privileged containers, arbitrary daemons,
-opaque volume behavior, and real Linux networking remain unsupported unless a
-specific browser adapter exists.
+PocketStack is not a Docker replacement. Privileged containers, arbitrary
+daemons, opaque volumes, and real Linux networking stay unsupported unless a
+browser adapter exists — in which case `analyze` reports the gap and how to
+[convert it](docs/convert/index.md).
 
 ## Install
 
@@ -47,104 +41,45 @@ npm run build:runtime
 go build -o bin/pocketstack ./cmd/pocketstack
 ```
 
-The JavaScript toolchain targets the current Node line, Node 26.
+Full instructions and prerequisites: [installation](docs/guide/installation.md).
 
-## Quick Start
-
-Analyze a Compose project:
+## Quick start
 
 ```sh
+# See which services map to a browser adapter
 pocketstack analyze -f compose.yaml
-```
 
-The analyzer returns a browser-readiness score, supported adapters, blockers,
-and next steps for services that need to be converted into browser-native
-pieces.
-
-Generate a browser-only demo:
-
-```sh
+# Generate a static, browser-only demo
 pocketstack demo -f compose.yaml -o pocketstack-demo
 ```
 
-Serve `pocketstack-demo/` from any static host. Frontend/WebContainer and some
-WASI demos require COOP/COEP headers; PocketStack emits host config files when
-they are needed. See [docs/HOSTING.md](docs/HOSTING.md).
+Serve `pocketstack-demo/` from any static host. Some demos need COOP/COEP
+headers; PocketStack emits the host config when they do. Walk through it in
+[getting started](docs/guide/getting-started.md), then see [hosting](docs/deploy/hosting.md).
 
 ## Studio
 
-PocketStack Studio is a static browser page for quick compatibility checks.
-Paste Compose YAML, upload a Compose file, and optionally add the project
-folder so Studio can inspect mounted assets.
+[PocketStack Studio](https://ramazankara.github.io/pocketstack/studio/) is a
+static browser page for quick compatibility checks — paste or upload Compose
+YAML and read the readiness report, entirely in the tab. Run it locally with
+`make studio`.
 
-Use the hosted Studio at <https://ramazankara.github.io/pocketstack/studio/>,
-or run it locally:
+## Documentation
 
-```sh
-make studio
-```
+Full docs are published at **<https://ramazankara.github.io/pocketstack/docs/>**
+(source under [`docs/`](docs/)):
 
-Open <http://127.0.0.1:4173/>. Use `make studio PORT=4174` if that port is
-busy.
-
-Studio runs entirely in the tab. It does not call a PocketStack backend,
-Docker daemon, runner, or hidden server.
-
-## Supported Adapters
-
-- `static-web`: copies document-root files from `nginx`, `httpd`, or `caddy`
-  services and previews them in an iframe.
-- `frontend`: packages a Node/Bun project for browser runtime execution.
-- `wasi`: runs an explicitly labeled prebuilt `.wasm` module.
-- `mock-http`: serves OpenAPI routes and JSON fixtures from the demo service
-  worker.
-- `postgres-pglite`: maps supported Postgres demos to resettable PGlite
-  browser storage.
-- `sqlite`: runs SQLite from SQL or seed database assets in the browser.
-
-Unsupported services are reported with concrete reasons and no server fallback.
-See [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) for exact behavior and
-limits.
-
-## Product Boundary
-
-PocketStack stays browser-native. It will not add a hidden Docker runner to
-make unsupported services appear compatible.
-
-That means full arbitrary Compose compatibility is not the v1 promise. The
-promise is better for static demos: when a stack can become browser-native,
-PocketStack packages it; when it cannot, PocketStack explains the gap and how
-to reshape the demo.
-
-## Examples
-
-The public site includes generated demos for the built-in examples:
-
-- [static web](https://ramazankara.github.io/pocketstack/demos/static-site/)
-- [mock API](https://ramazankara.github.io/pocketstack/demos/mock-api/)
-- [SQLite](https://ramazankara.github.io/pocketstack/demos/sqlite/)
-
-Studio-ready example projects live under
-[examples/uploaded](examples/uploaded/README.md). They are small enough to
-read, upload, and use as templates for your own Compose files.
-
-## Labels
-
-```yaml
-labels:
-  pocketstack.adapter: frontend|wasi|mock-http|postgres-pglite|sqlite
-  pocketstack.frontend.install: npm install
-  pocketstack.frontend.start: npm run dev -- --host 0.0.0.0
-  pocketstack.frontend.port: "5173"
-  pocketstack.wasi.module: hello.wasm
-  pocketstack.wasi.args: "--name PocketStack"
-  pocketstack.mock.openapi: openapi.yaml
-  pocketstack.mock.fixtures: fixtures
-  pocketstack.mock.port: "8080"
-  pocketstack.db.init: init.sql
-  pocketstack.db.seed: seed.sql
-  pocketstack.db.persist: indexeddb|memory
-```
+- [Getting started](docs/guide/getting-started.md) · [CLI reference](docs/guide/cli.md) · [Concepts & glossary](docs/guide/concepts.md) · [Troubleshooting](docs/guide/troubleshooting.md)
+- [Adapters & compatibility](docs/adapters/index.md) · [Labels](docs/adapters/labels.md) · [Conversion guide](docs/convert/index.md)
+- [Hosting](docs/deploy/hosting.md) · [Website integration](docs/deploy/website-integration.md) · [Manifest reference](docs/deploy/manifest.md)
+- [Architecture](docs/reference/architecture.md) · [Service URLs](docs/reference/service-urls.md) · [Contributing](docs/contribute/index.md)
+
+## Product boundary
+
+PocketStack stays browser-native. It will not add a hidden Docker runner to make
+unsupported services appear compatible. When a stack can become browser-native,
+PocketStack packages it; when it cannot, it explains the gap. See the
+[browser-only contract](docs/guide/concepts.md).
 
 ## Commands
 
@@ -154,20 +89,8 @@ pocketstack demo [-f compose.yaml] [-o pocketstack-demo]
 pocketstack version
 ```
 
-## Docs
+## Contributing
 
-- [Browser-only contract](docs/BROWSER_ONLY.md)
-- [Compatibility matrix](docs/COMPATIBILITY.md)
-- [Conversion guide](docs/CONVERSION_GUIDE.md)
-- [Architecture](docs/ARCHITECTURE.md)
-- [Static hosting](docs/HOSTING.md)
-- [Website integration](docs/WEBSITE_INTEGRATION.md)
-- [Browser testing](docs/BROWSER_TESTING.md)
-- [Release process](docs/RELEASE.md)
-- [Studio](studio/README.md)
-
-## Release Checks
-
-```sh
-make release-check
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[development guide](docs/contribute/index.md). Report security issues per
+[SECURITY.md](SECURITY.md). Licensed under [MIT](LICENSE).

docs/.vitepress/config.ts

@@ -0,0 +1,107 @@
+import { defineConfig } from 'vitepress'
+
+// The docs site is published under the project Pages subpath:
+// https://ramazankara.github.io/pocketstack/docs/
+export default defineConfig({
+  title: 'PocketStack',
+  description:
+    'Turn browser-compatible Docker Compose projects into static, browser-native demos.',
+  base: '/pocketstack/docs/',
+  lang: 'en-US',
+  cleanUrls: true,
+  lastUpdated: true,
+  // Strict: the build fails on broken internal links.
+  ignoreDeadLinks: false,
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide/getting-started' },
+      { text: 'Adapters', link: '/adapters/' },
+      { text: 'Convert', link: '/convert/' },
+      { text: 'Deploy', link: '/deploy/hosting' },
+      { text: 'Reference', link: '/reference/architecture' },
+      {
+        text: 'Try it',
+        items: [
+          { text: 'Studio', link: 'https://ramazankara.github.io/pocketstack/studio/' },
+          { text: 'Demos', link: 'https://ramazankara.github.io/pocketstack/demos/' },
+        ],
+      },
+    ],
+    sidebar: {
+      '/guide/': [
+        {
+          text: 'Guide',
+          items: [
+            { text: 'Getting started', link: '/guide/getting-started' },
+            { text: 'Installation', link: '/guide/installation' },
+            { text: 'CLI reference', link: '/guide/cli' },
+            { text: 'Concepts & glossary', link: '/guide/concepts' },
+            { text: 'Troubleshooting', link: '/guide/troubleshooting' },
+          ],
+        },
+      ],
+      '/adapters/': [
+        {
+          text: 'Adapters',
+          items: [
+            { text: 'Overview & matrix', link: '/adapters/' },
+            { text: 'Labels', link: '/adapters/labels' },
+            { text: 'Static web', link: '/adapters/static-web' },
+            { text: 'Frontend', link: '/adapters/frontend' },
+            { text: 'Mock HTTP', link: '/adapters/mock-http' },
+            { text: 'SQLite', link: '/adapters/sqlite' },
+            { text: 'Postgres (PGlite)', link: '/adapters/postgres-pglite' },
+            { text: 'WASI', link: '/adapters/wasi' },
+          ],
+        },
+      ],
+      '/convert/': [
+        { text: 'Convert', items: [{ text: 'Conversion guide', link: '/convert/' }] },
+      ],
+      '/deploy/': [
+        {
+          text: 'Deploy',
+          items: [
+            { text: 'Hosting & headers', link: '/deploy/hosting' },
+            { text: 'Website integration', link: '/deploy/website-integration' },
+            { text: 'Manifest reference', link: '/deploy/manifest' },
+          ],
+        },
+      ],
+      '/reference/': [
+        {
+          text: 'Reference',
+          items: [
+            { text: 'Architecture', link: '/reference/architecture' },
+            { text: 'Service URLs', link: '/reference/service-urls' },
+          ],
+        },
+      ],
+      '/contribute/': [
+        {
+          text: 'Contributing',
+          items: [
+            { text: 'Development setup', link: '/contribute/' },
+            { text: 'Releasing', link: '/contribute/releasing' },
+            { text: 'Browser testing', link: '/contribute/browser-testing' },
+          ],
+        },
+      ],
+      '/release-notes/': [
+        { text: 'Release notes', link: '/release-notes/' },
+      ],
+    },
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/ramazankara/pocketstack' },
+    ],
+    search: { provider: 'local' },
+    editLink: {
+      pattern: 'https://github.com/ramazankara/pocketstack/edit/main/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+    footer: {
+      message: 'Browser-native demos. No hidden server, no runner, no Docker at demo time.',
+      copyright: 'MIT © Ramazan Kara',
+    },
+  },
+})