feat(site): publish searchable docs and product showcase

Author: khuonghung

.github/workflows/deploy-site.yml

@@ -2,6 +2,16 @@ name: Deploy static landing page
 
 on:
   workflow_dispatch:
+  push:
+    branches: [master]
+    paths:
+      - 'site/**'
+      - 'docs/**'
+      - 'scripts/build-site.mjs'
+      - 'deploy/compose/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - '.github/workflows/deploy-site.yml'
 
 permissions:
   contents: read
@@ -25,11 +35,26 @@ jobs:
       - name: Check out source
         uses: actions/checkout@v7
 
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: pnpm
+
+      - name: Install build dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts --filter kintsugi
+
+      - name: Build landing page and documentation
+        run: pnpm site:build
+
       - name: Upload landing page
         uses: actions/upload-pages-artifact@v4
         with:
-          path: site
+          path: .site-dist
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4

.gitignore

@@ -19,3 +19,6 @@ __pycache__/
 
 # CLI packages built by `pnpm release:cli`
 /releases/
+
+# Generated public landing page and documentation
+/.site-dist/

deploy/compose/README.md

@@ -11,5 +11,6 @@ The app and worker images are defined by [`Dockerfile.app`](../../Dockerfile.app
 
 Runtime jobs run inside `worker`, each in its own job workspace under the data directory ([ADR-0029](../../docs/decisions/0029-job-workspaces-instead-of-os-sandboxes.md)): no Docker socket, no per-job container and no OS-level sandbox. The worker image therefore carries the standard script environment (git 2.40+, Python 3.12 and Node 22 with their standard libraries only) and runs as a non-root user. Jobs are not network-isolated: to restrict egress, attach the worker to a network that reaches only Postgres, the Git servers and the LLM providers.
 
-- How to install, configure GitHub Actions and upgrade: [installation guide](../../docs/guides/installation.md)
+- Install using the published app and worker images: [Docker image guide](../../docs/guides/docker-images.md)
+- Build and deploy your own images through GitHub Actions: [installation guide](../../docs/guides/installation.md)
 - How it fits together: [deployment view](../../docs/architecture/07-deployment-view.md)

docs/README.md

@@ -12,7 +12,7 @@ The documentation is organized by **what the reader needs**, following [Diátaxi
 | [guides/](guides/) | How-to | accomplish a task: install, configure, work on a migration task |
 | [development/](development/) | Delivery record | review implementation status, plans, open work, and verification evidence |
 
-Tutorials (learning-oriented walkthroughs) will be added once a first release exists.
+Start with [Your first modernization project](guides/first-project.md) for a walkthrough of the implemented development flow. Release and client-compatibility limits are stated in the linked references.
 
 ## Map
 
@@ -68,6 +68,9 @@ Tutorials (learning-oriented walkthroughs) will be added once a first release ex
 - [Configuration](reference/configuration.md): installation environment variables
 
 **Guides**
+- [Deploy with the published Docker images](guides/docker-images.md)
+- [Your first modernization project](guides/first-project.md)
+- [Member guideline: connect your AI client](guides/member-quickstart.md)
 - [Install Kintsugi](guides/installation.md)
 - [Build a project (register repos, write standards)](guides/build-project.md)
 - [Define a project's design templates](guides/define-design-templates.md)

docs/guides/docker-images.md

@@ -0,0 +1,99 @@
+# Deploy with the published Docker images
+
+Run Kintsugi on your own Linux host using the same app and worker images published by this repository. You do not need to build the TypeScript workspace or configure a GitHub Actions deployment to use them.
+
+## Requirements
+
+- Docker Engine 24+ and Docker Compose v2.20+ on a Linux host. Start with 4 vCPU, 16 GB RAM and 100 GB disk, then size for repository storage and concurrent jobs.
+- Access to GHCR, your Git servers and the LLM providers you configure.
+- A DNS name and a TLS reverse proxy for shared access; an SSH tunnel is sufficient for a local evaluation.
+
+The shipped images are `ghcr.io/evoelsewhere/kintsugi-app` and `ghcr.io/evoelsewhere/kintsugi-worker`. Both are published with `latest` and `sha-<full-commit>` tags by the [image workflow](../../.github/workflows/deploy.yml). Use the **same tag for both**. `latest` is the latest published development build, not a stable release. Pin `sha-<full-commit>` for repeatable installations and upgrades. Check the image's platform support before choosing a host.
+
+## 1. Download the Compose package
+
+Use the Compose bundle from the same commit as your chosen images. Replace `FULL_COMMIT_SHA` with the full commit from a successful **Build and deploy Kintsugi** run:
+
+```sh
+mkdir -p kintsugi
+cd kintsugi
+KINTSUGI_COMMIT=FULL_COMMIT_SHA
+curl -fL "https://raw.githubusercontent.com/evoelsewhere/kintsugi/$KINTSUGI_COMMIT/deploy/compose/docker-compose.yml" -o docker-compose.yml
+curl -fL "https://raw.githubusercontent.com/evoelsewhere/kintsugi/$KINTSUGI_COMMIT/deploy/compose/.env.example" -o .env
+chmod 600 .env
+```
+
+The package starts three services: the app (API and portal), the worker (runtime, orchestration and Git writes), and PostgreSQL with pgvector. PostgreSQL is the only datastore; documents stay in Git.
+
+## 2. Set your installation values
+
+Edit the private `.env` file:
+
+```dotenv
+KINTSUGI_REGISTRY=ghcr.io/evoelsewhere
+KINTSUGI_VERSION=sha-FULL_COMMIT_SHA
+KINTSUGI_HTTP_BIND=127.0.0.1
+KINTSUGI_HTTP_PORT=8080
+KINTSUGI_PUBLIC_URL=http://localhost:8080
+KINTSUGI_DATA_DIR=/srv/kintsugi/data
+KINTSUGI_BOOTSTRAP_ADMIN_USER=admin
+```
+
+Set `KINTSUGI_SECRET_KEY` to a newly generated base64 32-byte key, `POSTGRES_PASSWORD` to a random hexadecimal password, and `KINTSUGI_BOOTSTRAP_ADMIN_PASSWORD` to a unique password of at least eight characters. Generate values locally and paste them into `.env`:
+
+```sh
+openssl rand -base64 32
+openssl rand -hex 32
+openssl rand -hex 16
+```
+
+Keep `.env` private. Preserve the encryption key for the lifetime of the database and back it up securely; replacing it makes stored Git tokens and LLM credentials unreadable. Exact settings: [configuration reference](../reference/configuration.md).
+
+Create the data directory and assign it to the non-root worker user:
+
+```sh
+sudo mkdir -p /srv/kintsugi/data
+sudo chown 10001:10001 /srv/kintsugi/data
+```
+
+If you chose a different `KINTSUGI_DATA_DIR`, use that directory in both commands.
+
+## 3. Pull and start
+
+If GHCR requires authentication, run `docker login ghcr.io -u YOUR_GITHUB_USERNAME` and enter a token with `read:packages` at its password prompt. Never put the token in `.env` or in shell arguments. Public packages can be pulled without signing in.
+
+```sh
+docker compose config --quiet
+docker compose pull
+docker compose up -d --wait
+docker compose ps
+```
+
+The app runs database migrations on startup. `docker compose ps` should show a healthy app and database and a running worker. Investigate startup errors with:
+
+```sh
+docker compose logs --tail=100 app worker
+```
+
+The default port binds only to loopback. From your computer, open a tunnel to the host:
+
+```sh
+ssh -L 8080:127.0.0.1:8080 username@your-host
+```
+
+Visit `http://localhost:8080`, sign in with the bootstrap account you configured, and change its password. For shared access, configure a TLS reverse proxy to `127.0.0.1:8080`, set `KINTSUGI_PUBLIC_URL` to the public HTTPS origin and recreate the containers with `docker compose up -d --wait`. Expose only the app through the proxy.
+
+## 4. Configure and run your first project
+
+Configure LLM providers, Git connections and permissions in the portal, then follow the [first project walkthrough](first-project.md). Provider keys and Git tokens belong in the portal, which encrypts them in PostgreSQL. Member CLI installers are served by your own installation at `/guideline`.
+
+## Upgrade, backup and recovery
+
+1. Back up PostgreSQL and the private `.env` before upgrading. For a small installation, create a database dump with `docker compose exec -T postgres pg_dump -U kintsugi -Fc kintsugi > kintsugi-backup.dump`. Protect the backup as sensitive data and test restoring it on a separate installation.
+2. Preserve the matching Compose package and image tag. Back up the Git repositories at their source; also preserve imported repositories that exist only in `KINTSUGI_DATA_DIR`.
+3. Download the Compose bundle at the new image commit, inspect configuration changes and set the new `KINTSUGI_VERSION` for both services.
+4. Run `docker compose pull`, then `docker compose up -d --wait`. Verify sign-in, repository sync and worker status in Monitoring.
+
+Database migrations may prevent an image-only downgrade. Recovery can require restoring the pre-upgrade database together with its matching encryption key and images. `docker compose down` stops the stack; do not use `down -v` unless you intend to delete its database volume.
+
+To build and deploy images through your own GitHub Actions workflow instead, see [installation and automated deployment](installation.md).

docs/guides/first-project.md

@@ -0,0 +1,62 @@
+# Your first modernization project
+
+This walkthrough takes an installed Kintsugi portal from an empty project to a reviewed unit. It covers the implemented assess, understand, design, member build and runtime review flow. The wider P0–P4 delivery method includes activities the team performs outside the portal; see the [delivery pipeline](../methodology/delivery-pipeline.md).
+
+## 1. Prepare the installation
+
+An installation administrator first [deploys the Docker images](docker-images.md), adds a [runtime LLM provider](configure-llm-providers.md), and configures Git servers and credentials in Settings → Git. Grant users the installation permissions and explicit Project Access they need. A role alone does not give a member access to every project.
+
+Use a small application or a representative pilot. Have its legacy source, an empty document repository and scaffolded target repositories ready. The runtime reads source; members implement in the target repositories with their own Git credentials.
+
+## 2. Register the project and its standards
+
+In **Administration → Projects**, create a project, select its single document repository, add an application and link its `legacy`, optional `legacy-data`, and `target` repositories. Publish `kintsugi.yaml` with the starter structure, review the pull request and merge it. Wait for repository sync before running a stage.
+
+Write target conventions, legacy-to-target mappings, review rules and design templates in `01-standards/`. Put shared architecture and components under `02-architecture/`. These are Markdown documents, reviewed in Git. Use [Build a project](build-project.md) for the exact setup and [Define design templates](define-design-templates.md) for the design contract.
+
+## 3. Assess the application
+
+Open **Delivery → Assessment & Catalog**, select the project and application, then start assessment. Review its runs and logs. The resulting document pull request contains the inventory, topology, catalog and rebuild assessment.
+
+Check that the catalog identifies meaningful units, source references match the selected commit, and reported risks are supported by evidence. Review and merge the document pull request, then let Kintsugi sync it. The catalog is the menu for the next step; a successful job is not a human approval.
+
+## 4. Understand selected units
+
+Open **AS-IS Understanding → Catalog** and select a few representative items or a module. Run understanding on that selection. An optional understanding plan recommends an order based on dependencies; people choose the scope.
+
+Review each unit's rules, specification, data objects, findings and traceability in the document pull request. Resolve uncertainty with the people who know the legacy behavior; do not assume an AI statement is confirmed. Merge approved results. Generated application views are rebuilt from the merged units.
+
+## 5. Generate and review a design set
+
+In **Unit Design**, select understood units and a design set defined by your project's templates. Confirm its prerequisites: the relevant standards, common design and any earlier design sets must be available at the chosen document revision.
+
+Run the design, then inspect its proposed documents in Git. Review the handling of each business rule, interfaces, data changes, test expectations and unresolved decisions. Merge the accepted design before a member builds it. The number and names of design sets come from your project; the engine does not impose a stack.
+
+## 6. Connect a member's AI client
+
+Follow the [member guideline](member-quickstart.md) to install the CLI from **your installation's** `/guideline`, sign in to the project, run `kintsugi init`, and install the permitted `modernize` plugin. An administrator enables it under the project's Member plugins settings.
+
+In a fresh client session opened in the target repository, use the plugin's build command with the unit path. Claude Code uses:
+
+```text
+/modernize:build billing/invoice my-project
+```
+
+Replace the example unit and project with the actual IDs. Codex receives the command as a skill; select the installed `modernize` build skill in its skill picker. The [client reference](../reference/member-cli.md) explains differences between clients.
+
+Review the proposed implementation plan, let the member's assistant implement and test it, and inspect the canary that proves the tests can fail. The member commits the change and opens a merge request. Record its URL and full head commit through the build flow so the portal can associate it with the unit.
+
+## 7. Request an independent review
+
+Open **Delivery → Build** and check the recorded merge request and commit for the unit. Request a runtime review. It reads that revision against the unit's rules, merged design and project standards; it does not execute the target code or modify the merge request.
+
+Review findings in the proposed `_build/review.md` document. The member fixes the code, reruns tests and records the new merge request revision before requesting another review. A person decides acceptance. Clean-build verification is a later stage; a runtime review alone does not certify that the code builds.
+
+## 8. Monitor and repeat
+
+- **Monitoring**: inspect stage runs, document writes, repository sync and worker health. Read errors before retrying a failed run.
+- **Governance → Telemetry**: inspect model calls, tokens, cache reads and cost.
+- **Monitoring → Members**: inspect bounded plugin activity. Raw client transcripts remain on the member's machine.
+- **Gates**: record the human decision against the relevant evidence; follow your project's P0–P4 process.
+
+Run a small pilot first, improve standards through pull requests, then expand by wave. Keep legacy behavior, design decisions, implementation and tests traceable to their Git revisions.

docs/guides/installation.md

@@ -1,5 +1,7 @@
 # Install Kintsugi
 
+To use the images already published by this project, start with [Deploy with the published Docker images](docker-images.md). This page covers building and deploying your own images through GitHub Actions.
+
 Kintsugi runs as a Docker Compose installation with one app container, one worker container, and PostgreSQL. The repository's GitHub Actions workflow builds and publishes the app and worker images to GHCR and deploys commits from `master` over SSH.
 
 ## Before you start

docs/guides/member-quickstart.md

@@ -0,0 +1,89 @@
+# Member guideline: connect your AI client
+
+Use Kintsugi with the AI client already on your machine. The CLI signs you in and provides a local MCP bridge for project documents and permitted plugins. It does not call a model or write to your code repository.
+
+## Before you start
+
+Ask your administrator for the installation's HTTPS URL, your project ID and an account with `member.read` and explicit Project Access. Install Node.js 22.19 or newer and a supported Claude Code, Codex or GitHub Copilot client. On Linux, install `libsecret-tools` and run a Secret Service provider such as GNOME Keyring or KWallet.
+
+This flow is implemented in the development workspace. Check [client compatibility evidence](../reference/member-client-compatibility.md) for tested versions and remaining release gates.
+
+## 1. Install from your installation
+
+Open **Guideline** (`/guideline`) in your Kintsugi portal. It provides the exact commands and downloadable packages with checksums for that installation. Replace the example origin below with yours.
+
+macOS / Linux:
+
+```sh
+curl -fsSL https://kintsugi.example.internal/api/v1/releases/latest/install.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+powershell -ExecutionPolicy Bypass -Command "irm https://kintsugi.example.internal/api/v1/releases/latest/install.ps1 | iex"
+```
+
+Open a new terminal, add the installer-provided PATH entry if needed, and check:
+
+```sh
+kintsugi --version
+```
+
+The installer checks the package hash and remembers the installation URL. Run it again to update the CLI in place. Manual packages are available on the same Guideline page.
+
+## 2. Sign in and set up clients
+
+```sh
+kintsugi login my-project
+kintsugi init
+```
+
+Replace `my-project` with your actual project ID. In the browser, review the requested project and approve access. `init` lists detected clients and asks which to configure and whether to install globally or for the current workspace. Codex and Copilot use global setup; Claude Code supports workspace setup. Restart the client afterwards.
+
+Codex Desktop setup stages a personal marketplace; finish installing the connector in the app's Plugins Directory. It does not yet distribute member plugins through that staged path.
+
+## 3. Install a permitted plugin
+
+```sh
+kintsugi plugins list
+kintsugi install plugin modernize --all
+```
+
+If no plugin is available, ask the project's administrator to enable it for you. Start a new client session. Claude Code exposes `/modernize:build <module>/<unit> [project]`. Codex exposes the build command as a generated skill; select it with `$` or `/skills`. Copilot exposes a plugin skill. Trust the reporting hook in Codex's `/hooks` when requested.
+
+The `modernize` build flow reads the rules and merged design, proposes a plan for approval, implements and tests the unit locally, checks a canary, and records the unit's test result and merge request. See the [first project walkthrough](first-project.md) for the complete review loop.
+
+## 4. Check the connection
+
+```sh
+kintsugi auth status
+kintsugi project list
+kintsugi document tree 01-standards
+kintsugi doctor
+```
+
+In the AI client, ask it to list your Kintsugi projects and read a relevant standard through the connector. Documents are read from Git at a branch or commit. A successful `doctor` check verifies the runtime, credential and API read, not full client compatibility.
+
+## Maintain or disconnect
+
+```sh
+kintsugi install fetch modernize
+kintsugi remove modernize --all
+kintsugi auth logout
+```
+
+`auth logout` revokes the connection and removes the local credential. Access tokens stay in memory, rotating refresh credentials live in the operating system credential store, and profiles contain nonsecret configuration. Administrators can revoke connections in the portal.
+
+## Troubleshooting
+
+| Symptom | Next step |
+|---|---|
+| `kintsugi: command not found` | Open a new terminal and add the PATH line printed by the installer. |
+| No accessible project | Check the requested project ID, `member.read`, and explicit Project Access with an administrator. |
+| Plugin is missing | Check project plugin access, run `plugins list`, and restart the client after installation. |
+| Linux credential-store error | Install `libsecret-tools`, unlock the running keyring and sign in again. |
+| Private certificate authority | Use the CLI's `--ca-file` option; see the full reference. |
+| Hook is skipped in Codex | Review and trust the installed hook in `/hooks`. |
+
+Exact commands, authorization, plugin safety and reporting behavior: [member CLI reference](../reference/member-cli.md).