docs: clarify git-native pack policy

Author: KHAL-DX

README.md

@@ -1,55 +1,33 @@
-# Mintlify Starter Kit
+# KHAL OS public docs
 
-Use the starter kit to get your docs deployed and ready to customize.
+This repository contains the public Mintlify documentation site for KHAL OS. It is the public-facing docs surface for product concepts, app/pack authoring, SDK usage, and release/customer handoff guidance.
 
-Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with
+## Local development
 
-- Guide pages
-- Navigation
-- Customizations
-- API reference pages
-- Use of popular components
-
-**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**
-
-## AI-assisted writing
-
-Set up your AI coding tool to work with Mintlify:
+Run commands from the repository root, where `docs.json` lives:
 
 ```bash
-npx skills add https://mintlify.com/docs
-```
-
-This command installs Mintlify's documentation skill for your configured AI tools like Claude Code, Cursor, Windsurf, and others. The skill includes component reference, writing standards, and workflow guidance.
-
-See the [AI tools guides](/ai-tools) for tool-specific setup.
-
-## Development
-
-Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
-
-```
-npm i -g mint
+npx --yes mint@latest dev
+npx --yes mint@latest broken-links
 ```
 
-Run the following command at the root of your documentation, where your `docs.json` is located:
+If you prefer a global CLI, install Mintlify with `npm i -g mint` and run `mint dev` or `mint broken-links`.
 
-```
-mint dev
-```
+## Public/private boundary
 
-View your local preview at `http://localhost:3000`.
+These docs are public. Do not add secrets, tokens, credentials, customer identifiers, private hostnames, internal IPs, live monitoring URLs, admin usernames, migration/cutover notes, or operator-only runbook commands. Keep production operations and private topology in internal Hermes/KHAL runbooks unless Felipe explicitly approves publication.
 
-## Publishing changes
+## Pack distribution policy
 
-Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
+Pack/app repos are git-native: Marketplace/App Store installation reads the git repo and `khal-app.json`, then builds/loads the app from that source. Do not document `pack-*` repos as npm or GitHub Packages artifacts.
 
-## Need help?
+The npm packages that belong in public docs are the app-kit/framework packages only:
 
-### Troubleshooting
+- `@khal-os/sdk`
+- `@khal-os/ui`
+- `@khal-os/types`
+- `@khal-os/dev-cli`
 
-- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
-- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
+## Review requirement
 
-### Resources
-- [Mintlify documentation](https://mintlify.com/docs)
+Open a PR for documentation changes and request review before publishing or merging to the default branch. Public docs changes need product/schema review for technical truth and public/private boundary review for safety.

dev/local-dev-and-testing.mdx

@@ -23,7 +23,7 @@ bun run watch
 ```
 </CodeGroup>
 
-The build produces CJS + ESM + `.d.ts` outputs into `package/dist/`. The publish pipeline only ships what's under `package/`.
+The build produces frontend bundle outputs into `package/dist/` when the current build pipeline is available. Pack/app repos are installed from git; do not describe `package/` as an npm publish artifact.
 
 ## Typecheck and lint
 
@@ -85,17 +85,19 @@ For full-stack packs, a lightweight integration test talks to your service over
   </Step>
 </Steps>
 
-## The `khal-dev` QA CLI
+## The `khal` developer CLI
 
-The `@khal-os/dev-cli` package ships `khal-dev` — a pack-focused QA toolkit. Subcommands live under `app-kit/packages/dev-cli/src/commands/`.
+The `@khal-os/app-kit` package ships the `khal` binary. Developer-loop commands live under `khal dev`; run `khal dev --help` on your installed copy for the current list.
 
 Key commands:
 
 - `khal new app <name>` — scaffold a new pack from the bundled `app` template (also `khal new service <name>` and `khal new workflow <name>`).
-- `khal-dev qa <sub>` — the QA family. Inspect `app-kit/packages/dev-cli/src/commands/qa/` for the current list of sub-checks; `khal-dev qa --help` on your installed copy is authoritative.
+- `khal dev design-system --no-browser` — serve the bundled feature catalog without launching a browser, useful for CI/tests.
+- `khal dev manifest` — validate and inspect a `khal-app.json` manifest.
+- `khal dev qa <sub>` — the QA family. `khal dev qa --help` on your installed copy is authoritative for the current subcommands.
 
 <Note>
-The exact QA subcommand list evolves with the toolchain. Run `khal-dev qa --help` for the live list rather than memorizing it.
+The exact QA subcommand list evolves with the toolchain. Run `khal dev qa --help` for the live list rather than memorizing it.
 </Note>
 
 ## Debug tips
@@ -116,14 +118,14 @@ The exact QA subcommand list evolves with the toolchain. Run `khal-dev qa --help
 </CardGroup>
 
 <Frame>
-  <img alt="khal-dev qa output during a local test run" src="/images/khal-dev-qa.png" />
+  <img alt="khal dev qa output during a local test run" src="/images/khal-dev-qa.png" />
 </Frame>
 
 ## What's next
 
 <CardGroup cols={2}>
   <Card title="Publish your pack" icon="upload" href="/release/publish-your-pack">
-    Push → CI builds → publish.
+    Push → CI builds → git-native release/install.
   </Card>
   <Card title="khal-app.json reference" icon="file-lines" href="/reference/khal-app-json-schema">
     The full manifest schema.

docs.json

@@ -74,7 +74,8 @@
             "group": "Patterns",
             "pages": [
               "patterns/frontend-only-pack",
-              "patterns/full-stack-pack"
+              "patterns/full-stack-pack",
+              "patterns/design-system-reference-app"
             ]
           }
         ]

getting-started/install-dependencies.mdx

@@ -1,75 +1,78 @@
 ---
 title: "Install dependencies"
-description: "Which package manager to use where — pnpm for the SDK workspace, bun for pack-* repos — and the commands that get everything compiling."
+description: "Which package manager to use where — pnpm for app-kit and current khal-new app repos, bun only where an older repo already commits Bun metadata."
 ---
 
-KhalOS uses two package managers on purpose. The **SDK workspace** (the `@khal-os/*` packages you'll import into your pack) is a `pnpm` monorepo. Each **`pack-*` repo** (including `pack-template`) is a `bun` workspace. Knowing which tool runs where is the only setup detail that trips up first-time contributors.
+KhalOS uses package managers by repo contract. The **app-kit workspace** publishes the framework packages and the `khal` CLI. Current apps scaffolded with `khal new` use the package manager emitted in their next-steps output; older pack repos may still be Bun workspaces. When in doubt, follow the lockfile and scripts committed in the repo you are editing.
 
 ## TL;DR
 
 <CardGroup cols={2}>
   <Card title="pnpm" icon="box">
-    For the `@khal-os/*` SDK workspace. `pnpm install`, `pnpm build`, `pnpm typecheck`, `pnpm lint`.
+    For the app-kit framework workspace. `pnpm install`, `pnpm build`, `pnpm typecheck`, `pnpm lint`.
   </Card>
-  <Card title="bun" icon="bolt">
-    For every `pack-*` repo (the scaffold you clone from `pack-template`). `bun install`, `bun run build`, `bun run typecheck`.
+  <Card title="pnpm in new app repos" icon="box-open">
+    Current `khal new app` output says `pnpm install`, then `khal start`. Build with the repo's scripts, for example `pnpm build` when the scaffold exposes `"build": "khal build"`.
+  </Card>
+  <Card title="bun in older pack repos" icon="bolt">
+    Use Bun only where the repo already commits Bun metadata and scripts. Typical older commands are `bun install`, `bun run build`, `bun run typecheck`.
   </Card>
 </CardGroup>
 
 ## Node version
 
-Install **Node 20 or newer**. The `@khal-os/*` packages target modern Node and `bun` itself installs cleanly on 20.x. If you use `nvm`, run `nvm use` inside any repo that ships an `.nvmrc`.
+Install **Node 20 or newer**. The app-kit packages target modern Node, and both `pnpm` and `bun` install cleanly on 20.x. If you use `nvm`, run `nvm use` inside any repo that ships an `.nvmrc`.
 
 ```bash
 node --version   # v20.x or newer
 pnpm --version   # any recent release
-bun --version    # 1.x
+bun --version    # 1.x, only needed for repos that already use Bun
 ```
 
-## The SDK workspace — `pnpm`
+## The app-kit workspace — `pnpm`
 
-The SDK workspace ships the four framework packages your pack will depend on: `@khal-os/sdk`, `@khal-os/ui`, `@khal-os/types`, and `@khal-os/dev-cli`. It uses `pnpm` and Turbo under the hood.
+The app-kit workspace ships the framework packages your pack will depend on (`@khal-os/sdk`, `@khal-os/ui`, `@khal-os/types`) plus the `@khal-os/app-kit` package that exposes the `khal` CLI. It uses `pnpm` and Turbo under the hood.
 
 <CodeGroup>
-
 ```bash pnpm
 pnpm install        # install workspace deps
 pnpm build          # turbo run build — build every package
 pnpm typecheck      # turbo run typecheck across the workspace
 pnpm lint           # biome check
 pnpm lint:fix       # biome check --write .
 ```
-
 </CodeGroup>
 
-You usually don't need to run these yourself: the packages publish from CI to GitHub Packages, and your pack consumes them as ordinary npm dependencies. Install them here only if you're debugging an SDK issue or running a local snapshot of the SDK against your pack.
+Those framework packages may be consumed as npm dependencies by pack/app repos. That does not make `pack-*` repos npm packages; pack identity and install content remain git-native.
 
-## Pack repos — `bun`
+## Pack/app repos — follow the scaffold
 
-Every `pack-*` repo — including the scaffold you clone from `pack-template` — uses `bun` as both its package manager and its runtime. `bun install` is fast, workspaces are first-class, and the included bundler already matches the toolchain the template expects.
+Current `khal new app <name>` output tells you to run `pnpm install` and then `khal start`. The generated root `package.json` exposes `"dev": "khal dev"` and `"build": "khal build"`, so use the package manager that installs the root workspace and then run the scripts it provides.
 
 <CodeGroup>
-
-```bash bun
-bun install         # install pack deps
-bun run build       # build the frontend package
-bun run typecheck   # type-check all workspaces
-bun run lint        # biome lint
-bun run test        # run tests (if present)
+```bash Current khal new app
+pnpm install        # install app deps, as emitted by current scaffold next steps
+pnpm build          # runs khal build through the generated package.json script
+khal start          # start the local KhalOS dev loop
 ```
 
+```bash Older Bun pack repo
+bun install         # install deps when the repo already uses Bun
+bun run build       # build using that repo's existing script
+bun run typecheck   # type-check if the repo defines the script
+```
 </CodeGroup>
 
 <Callout type="warning">
-  Don't cross the streams. Running `pnpm install` inside a `pack-*` repo, or `bun install` inside the SDK workspace, will produce a lockfile the other tool ignores — and the next person on the repo will have to untangle it. When in doubt, check which lockfile is already committed.
+  Don't cross the streams. Running `bun install` in a pnpm scaffold, or `pnpm install` in an older Bun-only pack repo, can produce a lockfile the repo does not use. When in doubt, check which lockfile and scripts are already committed.
 </Callout>
 
 ## Verifying your setup
 
 After you've cloned the workspace, pick one of each and confirm both install cleanly:
 
 <Steps>
-  <Step title="SDK workspace">
+  <Step title="App-kit workspace">
     ```bash
     cd repos/app-kit
     pnpm install && pnpm build
@@ -78,18 +81,19 @@ After you've cloned the workspace, pick one of each and confirm both install cle
     `pnpm build` should finish with every package green in the Turbo summary.
   </Step>
 
-  <Step title="A reference pack">
+  <Step title="A scaffolded pack/app">
     ```bash
-    cd repos/pack-template
-    bun install && bun run build
+    khal new app hello-fde
+    cd hello-fde
+    pnpm install && pnpm build
     ```
 
-    `bun run build` should emit CJS + ESM + `.d.ts` outputs into `package/dist/`.
+    `pnpm build` should run the scaffold's `khal build` script and emit bundle outputs into `package/dist/` when the current build pipeline is available.
   </Step>
 </Steps>
 
 <Frame>
-  ![Split terminal showing pnpm install in app-kit on the left and bun install in pack-template on the right, both finishing green.](/images/getting-started/pnpm-bun-split.png)
+  ![Split terminal showing pnpm install in app-kit on the left and pnpm install in a khal new app repo on the right, both finishing green.](/images/getting-started/pnpm-bun-split.png)
 </Frame>
 
 ## Next steps
@@ -99,6 +103,6 @@ After you've cloned the workspace, pick one of each and confirm both install cle
     Scaffold a new pack with `khal new app <name>` and get a "Hello FDE" component shipping.
   </Card>
   <Card title="Pack anatomy" href="/packs/anatomy-of-a-pack">
-    A directory-level tour of everything inside a pack — manifest, frontend package, backend service, Helm chart, CI.
+    A directory-level tour of everything inside a pack — manifest, frontend source, backend service, Helm chart, CI.
   </Card>
 </CardGroup>

getting-started/your-first-pack.mdx

@@ -6,19 +6,51 @@ description: "Scaffold a pack with `khal new`, edit a React component, and see i
 A pack is a self-contained KhalOS app: a frontend React package plus an optional backend service, a manifest that declares both, and a Helm chart for shipping. In this walkthrough you'll go from an empty directory to a running "Hello FDE" pack in under ten minutes.
 
 <Callout type="info">
-  This page is the fast path. For the full pack contract — every manifest field, every CI workflow, every deploy mode — follow the **Next steps** links at the bottom.
+  This page is the fast path. For the full pack contract — every manifest field, every install mode, every design-system expectation — follow the **Next steps** links at the bottom.
+</Callout>
+
+<Callout type="warning">
+  Packs are installed from git. Do not add `.npmrc`, `publishConfig`, npm publish scripts/workflows, or `frontend.package` to a new pack manifest.
 </Callout>
 
 ## 1. Scaffold with `khal new`
 
 `@khal-os/app-kit` ships a `khal new` command that stamps out a complete pack locally. It bundles three templates — `app` (full-stack), `service` (backend-only), and `workflow` (Temporal) — and emits a runnable project with no network calls.
 
+Verify the CLI you are about to use:
+
+```bash
+khal --version
+khal new --list
+```
+
+Expected shape:
+
+```text
+1.x.y
+Bundled templates:
+  app        v1.x.y
+  service    v1.x.y
+  workflow   v1.x.y
+```
+
+Package note: the npm package is `@khal-os/app-kit` and its binary is `khal`. As of 2026-05-18, npm reports `latest` as `1.0.14` and `next` as `1.0.24`; use an installed, verified `khal` binary for scaffolding until the public `latest` tag is promoted to the release you want to document.
+
 ```bash
 khal new app <name>
 cd <name>
 ```
 
-Replace `<name>` with your pack's identifier — lowercase, hyphen-separated, and short. It becomes the Helm chart name, the manifest `id`, and the package name. `khal new` substitutes the token everywhere it appears in the bundled template.
+Replace `<name>` with your pack's identifier — lowercase, hyphen-separated, and short. It becomes the manifest `id`, local build workspace name, and any generated backend/chart names. `khal new` substitutes the token everywhere it appears in the bundled scaffold.
+
+Current scaffold output ends with:
+
+```text
+Next steps:
+  1. cd <name>
+  2. pnpm install
+  3. khal start
+```
 
 <Callout type="tip">
   Run `khal new` with no arguments to see the three available types and their one-line descriptions. Add `--list` to inspect the bundled template versions.
@@ -71,15 +103,14 @@ If your pack is **frontend-only**, delete the `service/` directory and remove th
 ## 4. Build and typecheck
 
 ```bash
-bun install
-bun run build
-bun run typecheck
+pnpm install
+pnpm build
 ```
 
-`bun run build` produces CJS + ESM bundles plus TypeScript declarations in `package/dist/`. `bun run typecheck` validates both the frontend package and the service (if present).
+Current `khal new app` scaffolds expose a root `"build": "khal build"` script. Run the scripts committed in your generated `package.json`; older pack repos may still expose separate `bun run build` or `bun run typecheck` scripts.
 
 <Frame>
-  ![Terminal showing bun run build output with dist artifacts listed, followed by a green bun run typecheck summary.](/images/getting-started/bun-build-success.png)
+  ![Terminal showing pnpm build output with dist artifacts listed and a green build summary.](/images/getting-started/bun-build-success.png)
 </Frame>
 
 ## 5. See it in the shell
@@ -115,4 +146,7 @@ You've got two paths to render your pack in a live shell:
   <Card title="Full-stack pack pattern" href="/patterns/full-stack-pack">
     The end-to-end reference pattern for packs with both a frontend and a backend service.
   </Card>
+  <Card title="Design-system reference app" href="/patterns/design-system-reference-app">
+    What to copy when you want your pack to look, install, and QA like a first-class KhalOS app.
+  </Card>
 </CardGroup>