Restructure public documentation

.github/styles/config/vocabularies/embucket/accept.txt

@@ -48,3 +48,13 @@ unpatched
 deployer
 anonymized
 bootable
+APIs?
+ARNs?
+[Dd]eployers?
+CLI
+[Ss]tatestore
+GitLab
+[Oo]pen-source
+TLS
+VPC
+OTEL

.github/workflows/docs-ci.yml

@@ -51,47 +51,10 @@ jobs:
         working-directory: ./docs
         run: pnpm prettier --check . 
 
-  smoke:
-    name: Docs Smoke Checks
-    runs-on: ubuntu-latest
-    needs: [format]
-    steps:
-      - uses: actions/checkout@v6
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: "22"
-      - name: Setup PNPM
-        uses: pnpm/action-setup@v4
-        with:
-          version: "10.11.0"
-          run_install: false
-      - name: Get pnpm store directory
-        id: pnpm-cache
-        shell: bash
-        run: |
-          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
-      - name: Setup pnpm cache
-        uses: actions/cache@v4
-        with:
-          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/docs/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
-      - name: Install dependencies
-        working-directory: ./docs
-        run: pnpm install
-      - name: Run Astro check
-        working-directory: ./docs
-        run: pnpm check
-      - name: Run docs smoke checks
-        working-directory: ./docs
-        run: pnpm smoke
-
   build:
     name: Validate Build
     runs-on: ubuntu-latest
-    needs: [format, smoke]
+    needs: [format]
     steps:
       - uses: actions/checkout@v6
       - name: Setup Node.js

.gitignore

@@ -7,11 +7,10 @@ data/
 .env
 metastore.yaml
 
-# Ignore only the root styles directory; allow .github/styles for Vale
-/styles/
-!/styles/config
-!.github/styles/
-!.github/styles/**
+# Vale styles — only keep custom vocabulary, ignore downloaded packages
+.github/styles/Google/
+.github/styles/write-good/
+.github/styles/.vale-config/
 
 **/*.rs.bk
 .DS_Store
@@ -20,3 +19,4 @@ metastore.yaml
 .log
 
 metastore.yaml
+docs/superpowers/

README.md

@@ -1,109 +1,51 @@
 # Embucket
 
-Embucket exposes a Snowflake-compatible API over lakehouse data. The repo currently ships two runtime artifacts:
+Embucket is a Snowflake-compatible query engine built on [Apache DataFusion](https://datafusion.apache.org/). It runs as an AWS Lambda function and uses S3 Tables (Apache Iceberg) for storage. Connect with any Snowflake-compatible tool or the [dbt-embucket](https://github.com/Embucket/dbt-embucket) adapter.
 
-- `embucketd` for local and self-hosted runs
-- `embucket-lambda` for AWS Lambda deployments
+## Key features
 
-## Choose your path
+- Snowflake v1 REST API compatibility
+- SQL dialect support via Apache DataFusion
+- AWS Lambda serverless deployment
+- S3 Tables (Iceberg/Parquet) storage
+- Official dbt adapter for analytics workflows
+- Snowflake CLI compatibility
 
-- **Start locally** if you want the fastest test or evaluation loop.
-- **Run from source** if you want to build `embucketd` yourself for local evaluation.
-- **Deploy on AWS Lambda** if you want the current serverless runtime.
-- **Connect dbt** if you want the recommended client path.
-- **Run Snowplow web analytics** if you want a fuller example on the Lambda + dbt path.
-- **Use S3 Tables** if you want the currently documented external catalog.
-- **Troubleshoot** if your client, auth, or runtime setup does not behave as expected.
+## Quick start
 
-Relevant guides live under `docs/src/content/docs/`:
-
-- `essentials/quick-start.mdx`
-- `essentials/runtime-modes.mdx`
-- `guides/aws-lambda.mdx`
-- `guides/dbt.mdx`
-- `guides/self-hosted.mdx`
-- `guides/snowplow.mdx`
-- `guides/s3-tables.mdx`
-- `guides/troubleshooting.mdx`
-
-If you want to build the local binary instead of using Docker, start with `docs/src/content/docs/guides/self-hosted.mdx`.
-
-If you want a fuller example on the recommended client path, start with `docs/src/content/docs/guides/snowplow.mdx`.
-
-## Support summary
-
-The current docs should make these distinctions explicit:
-
-- **Local mode** is the fastest path for tests and evaluation.
-- **AWS Lambda + dbt-embucket** is verified and is the recommended client path.
-- **AWS Lambda + Snowflake CLI over Function URL** is tested, but not production-ready because the Function URL is publicly reachable.
-- **Production-facing Lambda deployments** should avoid a public Function URL. The AWS Lambda guide includes an anonymized private API Gateway example.
-- **AWS S3 Tables** is the currently documented external catalog path.
-
-## Local quick start
-
-Run Embucket locally:
+Run Embucket locally with Docker:
 
 ```bash
 docker run --name embucket --rm -p 3000:3000 embucket/embucket
 ```
 
-Expected startup log:
-
-```text
-{"timestamp":"2025-07-01T15:35:05.687807Z","level":"INFO","fields":{"message":"Listening on http://0.0.0.0:3000"},"target":"embucketd"}
-```
-
-Configure Snowflake CLI for the local endpoint:
+See the full [Quick Start guide](https://docs.embucket.com/getting-started/quick-start/) for next steps.
 
-```bash
-snow --info
-
-# Add this connection block to your Snowflake CLI config file.
-[connections.local]
-host = "localhost"
-region = "us-east-2"
-port = 3000
-protocol = "http"
-database = "embucket"
-schema = "public"
-warehouse = "em.wh"
-account = "acc.local"
-user = "embucket"
-password = "embucket"
-```
+## Deploy
 
-Validate the connection and run a query:
+Deploy Embucket to AWS Lambda with the pre-built zip:
 
 ```bash
-snow connection test -c local
-snow sql -c local -q "SELECT 1 AS ok"
+aws s3 cp s3://embucket-releases/lambda/embucket-lambda-latest.zip .
 ```
 
-You can also open `http://127.0.0.1:3000/` to inspect the current Swagger/OpenAPI surface served by `embucketd`.
-
-## AWS Lambda quick pointer
+See the [AWS Lambda deployment guide](https://docs.embucket.com/deploy/aws-lambda/) for configuration and production setup.
 
-If you want the current serverless path, start with `docs/src/content/docs/guides/aws-lambda.mdx`.
-
-The current runtime is built from `crates/embucket-lambda` and can be deployed with:
-
-```bash
-make -C crates/embucket-lambda deploy
-```
+## Connect
 
-For test-only validation, you can expose a Function URL and connect Snowflake CLI to it. For production-facing traffic, keep the Lambda private and put an API gateway layer in front of it.
+- **Snowflake CLI** -- connect any Snowflake-compatible client to your Embucket endpoint. See the [Snowflake CLI guide](https://docs.embucket.com/connect/snowflake-cli/).
+- **dbt adapter** -- use `dbt-embucket` for analytics workflows. See the [dbt guide](https://docs.embucket.com/connect/dbt/).
 
-## dbt quick pointer
+## Documentation
 
-If you want the recommended client workflow, start with `docs/src/content/docs/guides/dbt.mdx`.
+- [Architecture](https://docs.embucket.com/reference/architecture/)
+- [Snowflake compatibility](https://docs.embucket.com/reference/snowflake/)
+- [Troubleshooting](https://docs.embucket.com/reference/troubleshooting/)
 
-The official adapter lives in the sibling repository `Embucket/dbt-embucket` and uses:
+## Contributing
 
-- `type: embucket`
-- `function_arn` to reach the deployed Lambda
-- `dbt debug` and `dbt run` as the verified end-to-end checks
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## S3 Tables quick pointer
+## License
 
-The current docs treat AWS S3 Tables as the supported external catalog path. Start with `docs/src/content/docs/guides/s3-tables.mdx` for the YAML shape, AWS prerequisites, and query flow.
+Embucket is licensed under the [Apache License 2.0](LICENSE).

docs/README.md

@@ -38,15 +38,12 @@ To ensure everything is working correctly:
 ### Project structure
 
 ```
-.
-├── public/
-├── src/
-│   ├── assets/
-│   ├── components/
-│   ├── content/
-│   │   ├── docs/
-│   └── content.config.ts
-└── astro.config.mjs
+docs/src/content/docs/
+  getting-started/    — Quick Start
+  deploy/             — AWS Lambda, Configuration
+  connect/            — Snowflake CLI, dbt adapter
+  tutorials/          — Snowplow web analytics
+  reference/          — Architecture, Snowflake compatibility, Troubleshooting
 ```
 
 Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its filename.

docs/astro.config.mjs

@@ -18,16 +18,28 @@ export default defineConfig({
       social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/embucket/embucket' }],
       sidebar: [
         {
-          label: 'Essentials',
-          autogenerate: { directory: 'essentials' },
+          label: 'Getting Started',
+          autogenerate: { directory: 'getting-started' },
         },
         {
-          label: 'Guides',
-          autogenerate: { directory: 'guides' },
+          label: 'Deploy',
+          autogenerate: { directory: 'deploy' },
         },
         {
-          label: 'Development',
-          autogenerate: { directory: 'development' },
+          label: 'Configuration',
+          autogenerate: { directory: 'configuration' },
+        },
+        {
+          label: 'Connect',
+          autogenerate: { directory: 'connect' },
+        },
+        {
+          label: 'Tutorials',
+          autogenerate: { directory: 'tutorials' },
+        },
+        {
+          label: 'Reference',
+          autogenerate: { directory: 'reference' },
         },
       ],
       customCss: ['./src/styles/global.css'],
@@ -46,6 +58,21 @@ export default defineConfig({
     plugins: [tailwindcss()],
   },
   redirects: {
-    '/': '/essentials/quick-start/',
+    '/': '/getting-started/quick-start/',
+    '/essentials/quick-start/': '/getting-started/quick-start/',
+    '/essentials/architecture/': '/reference/architecture/',
+    '/essentials/configuration/': '/configuration/configuration/',
+    '/deploy/configuration/': '/configuration/configuration/',
+    '/essentials/runtime-modes/': '/deploy/aws-lambda/',
+    '/essentials/snowflake/': '/reference/snowflake/',
+    '/essentials/support-matrix/': '/deploy/aws-lambda/',
+    '/guides/aws-lambda/': '/deploy/aws-lambda/',
+    '/guides/dbt/': '/connect/dbt/',
+    '/guides/snowflake-cli/': '/connect/snowflake-cli/',
+    '/guides/snowplow/': '/tutorials/snowplow/',
+    '/guides/troubleshooting/': '/reference/troubleshooting/',
+    '/guides/s3-tables/': '/deploy/aws-lambda/',
+    '/guides/self-hosted/': '/getting-started/quick-start/',
+    '/guides/end-to-end-dbt/': '/connect/dbt/',
   },
 });

docs/package.json

@@ -11,7 +11,6 @@
     "format": "prettier --write .",
     "ncu": "ncu -u",
     "preview": "astro preview",
-    "smoke": "node ./scripts/validate-docs-smoke.mjs",
     "start": "astro dev"
   },
   "dependencies": {