khal-os · namastex888 · May 21, 2026 · May 21, 2026
diff --git a/dev/fde-cli-quickstart.mdx b/dev/fde-cli-quickstart.mdx
@@ -6,7 +6,7 @@ description: 'Install the public khal CLI from npmjs, log in with WorkOS, scaffo
 This is the verified first-run path for a Field Delivery Engineer using the public `khal` CLI.
 
 <Warning>
-Install the CLI from **npmjs**. Do not configure GitHub Packages for this flow. If a GitHub Packages entry exists for app-kit, treat it as non-authoritative for FDE installs; npmjs is the registry FDEs use.
+Install the CLI from **npmjs**. npmjs is npm's default registry, so no registry flag is normally needed. Do not configure GitHub Packages for this flow; if a GitHub Packages entry exists for app-kit, treat it as non-authoritative for FDE installs.
 </Warning>
 
 ## 0. Prerequisites
@@ -19,30 +19,25 @@ npm --version     # npm 10+ works
 bun --version     # required by generated app/service/workflow repos
 ```
 
-If you will install from private GitHub app repos, authenticate GitHub too:
-
-```bash
-gh auth login
-gh auth status
-```
+Private KHAL app repos live in KHAL Gitea. Use the repo URL and credentials from the internal Gitea UI or onboarding note when you install from a private source. GitHub authentication is only relevant for the public docs repo and the GitHub-hosted app-kit/desktop exceptions.
 
 ## 1. Install `khal` from npmjs
 
 Use the package `@khal-os/app-kit`. The binary is `khal`.
 
 <CodeGroup>
 ```bash Global install
-npm install --registry=https://registry.npmjs.org/ --global @khal-os/app-kit@latest
+npm install --global @khal-os/app-kit@latest
 khal --version
 ```
 
 ```bash Project-local install
-npm install --registry=https://registry.npmjs.org/ --save-dev @khal-os/app-kit@latest
+npm install --save-dev @khal-os/app-kit@latest
 npx khal --version
 ```
 
 ```bash One-shot without installing globally
-npm exec --registry=https://registry.npmjs.org/ --package @khal-os/app-kit@latest -- khal --version
+npm exec --package @khal-os/app-kit@latest -- khal --version
 ```
 </CodeGroup>
 
@@ -144,7 +139,7 @@ A clean scaffold reports a passing summary and zero blocking checks:
 For a hosted app repo, always pass an explicit branch:
 
 ```bash
-khal install https://github.com/<org>/<app-repo> --branch dev --target dev --scope shared --dry-run --json
+khal install <private-khal-gitea-repo-url> --branch dev --target dev --scope shared --dry-run --json
 ```
 
 ## 6. Install after dry-run passes
@@ -158,7 +153,7 @@ khal install . --target dev --scope shared
 For a hosted repo:
 
 ```bash
-khal install https://github.com/<org>/<app-repo> --branch dev --target dev --scope shared
+khal install <private-khal-gitea-repo-url> --branch dev --target dev --scope shared
 ```
 
 If the target denies the mutation, ask for the permission named by the CLI. The current install path usually requires `os.marketplace.install`.
@@ -181,33 +176,33 @@ khal open <app-id> --target dev --check --json
 
 ```bash
 which khal
-npm view @khal-os/app-kit dist-tags --registry=https://registry.npmjs.org/ --json
+npm view @khal-os/app-kit dist-tags --json
 npm cache clean --force
-npm install --registry=https://registry.npmjs.org/ --global @khal-os/app-kit@latest
+npm install --global @khal-os/app-kit@latest
 ```
 
 ### GitHub Packages shows a different version
 
 Ignore it for FDE CLI installation. npmjs is canonical for `@khal-os/app-kit`.
 
-### Private GitHub repo fetch fails
+### Private Gitea repo fetch fails
 
-Authenticate source control first:
+Authenticate source control through the internal Gitea path from onboarding:
 
 ```bash
-gh auth login
-gh auth status
-ssh -T git@github.com
+tea login list
+tea whoami
+git ls-remote <private-khal-gitea-repo-url>
 ```
 
-Do not print or commit `GH_TOKEN` or `GITHUB_TOKEN`.
+For SSH remotes, register your SSH key in Gitea first and use the SSH clone URL. Do not print or commit tokens, credential-helper output, or private remote URLs in public docs/issues.
 
 ## What was dogfooded
 
 This page was written after running the path from a clean directory with npmjs `@latest`:
 
 ```bash
-npm install --registry=https://registry.npmjs.org/ @khal-os/app-kit@latest
+npm install @khal-os/app-kit@latest
 ./node_modules/.bin/khal --version
 ./node_modules/.bin/khal auth login --target dev --no-browser
 ./node_modules/.bin/khal new app fde-demo-app

diff --git a/dev/fde-environment-ladder.mdx b/dev/fde-environment-ladder.mdx
@@ -28,7 +28,7 @@ Use the same CLI shape at every rung; only the target changes:
 ```bash
 khal context --target dev --text
 khal doctor --target dev
-khal install https://github.com/<org>/<app-repo> --branch <branch> --target dev --scope shared --dry-run --json
+khal install <private-khal-gitea-repo-url> --branch <branch> --target dev --scope shared --dry-run --json
 ```
 
 The FDE should not mutate a shared or customer target until the dry-run is clean and the target identity is obvious. For first-run install/login/scaffold commands, see [FDE CLI quickstart](/dev/fde-cli-quickstart).
@@ -71,8 +71,8 @@ The remote code host mirror may be backed by Gitea. Treat that mirror as a trans
 
 A good Gitea mirror proof includes:
 
-- upstream GitHub repo and commit/ref;
-- Gitea mirror URL or remote name, without credentials;
+- authoritative Gitea repo and commit/ref;
+- any temporary mirror URL or remote name, without credentials;
 - agent host or SSH alias used to run the mirrored `dev-local` loop;
 - evidence that the mirrored run used the same manifest/env contract as local FDE work.
 
@@ -105,8 +105,8 @@ At this rung, an FDE should be able to explain:
 The CLI should behave like a Vercel-style deploy companion, but with explicit environment identity:
 
 ```bash
-khal deploy https://github.com/<org>/<app-repo> --branch <branch> --target local
-khal deploy https://github.com/<org>/<app-repo> --branch <branch> --target dev
+khal deploy <private-khal-gitea-repo-url> --branch <branch> --target local
+khal deploy <private-khal-gitea-repo-url> --branch <branch> --target dev
 ```
 
 Before mutating anything, the CLI should print:

diff --git a/dev/gitea-source-control.mdx b/dev/gitea-source-control.mdx
@@ -5,8 +5,8 @@ description: "How public GitHub docs and private KHAL engineering repositories f
 
 KHAL uses two source-control surfaces intentionally:
 
-- **Public GitHub repositories** for public documentation, public examples, and services that must integrate with public SaaS tools.
-- **Private KHAL Gitea** for internal product engineering, private packs, platform work, and day-to-day team collaboration.
+- **Private KHAL Gitea** for internal product engineering, private app repos, platform work, and day-to-day team collaboration.
+- **Public GitHub repositories** only for the public docs repo and repos that still need public SaaS integration, currently including app-kit and desktop.
 
 This split is a security boundary, not a temporary accident. Public docs should stay easy to publish and safe to expose; private engineering work should stay behind KHAL-controlled access.
 
@@ -76,7 +76,7 @@ When sharing evidence in public docs or public issues, redact private remote URL
 | Work surface | Source control | Deploy/publish path |
 | --- | --- | --- |
 | Public docs and FDE manual | Public GitHub docs repo | Mintlify |
-| Public example code | Public GitHub repo | GitHub + normal public CI |
+| GitHub-hosted exceptions such as app-kit/desktop | Public GitHub repo | GitHub + required public SaaS/cloud integrations |
 | Private KHAL platform/app work | Internal KHAL Gitea | Internal CI/deploy path for that repo |
 | Temporary mirrored checkout | Mirror/transport only | Not a source-of-truth change by itself |
 

diff --git a/getting-started/clone-workspace.mdx b/getting-started/clone-workspace.mdx
@@ -1,9 +1,9 @@
 ---
 title: "Clone the workspace"
-description: "One clone. One bootstrap. Every KhalOS repo checked out at consistent commits so you can jump between the SDK, reference packs, and your own pack freely."
+description: "How to fetch KHAL source from the right remote: private app/platform repos in Gitea, public docs/app-kit/desktop exceptions on GitHub."
 ---
 
-KhalOS is developed as a workspace of repositories wired together by a meta-repo. Cloning that meta-repo and running a single bootstrap script gives you the entire ecosystem on disk at known-good commits — the SDK you'll import, the reference packs you'll copy from, and the scaffold you'll start with.
+KHAL source now follows the split in [Source control for KHAL teams](/dev/gitea-source-control): private app/platform repos live in internal KHAL Gitea; public docs, app-kit, and desktop remain on GitHub because of their public docs/SaaS/cloud integration path. For most FDE app work, start from the private Gitea repo URL you received during onboarding, not a GitHub workspace clone.
 
 ## Before you start
 
@@ -14,39 +14,40 @@ KhalOS is developed as a workspace of repositories wired together by a meta-repo
 | Requirement | Why | Check |
 |---|---|---|
 | `git` ≥ 2.30 | Submodule features required by `init.sh` | `git --version` |
-| `gh` CLI, authenticated | HTTPS git auth is delegated to `gh auth git-credential` — no tokens in dotfiles | `gh auth status` |
+| Gitea access | Required for private app/platform repos | `tea login list` or your configured SSH key |
 | Node 20+ | `@khal-os/*` packages target modern Node | `node --version` |
 | `pnpm` | Workspace package manager for the SDK | `pnpm --version` |
-| `bun` | Runtime + package manager for `pack-*` repos | `bun --version` |
+| `bun` | Runtime + package manager for generated app/service/workflow repos | `bun --version` |
 
 ## Clone and bootstrap
 
 <Steps>
-  <Step title="Authenticate with GitHub">
-    Skip if you're already signed in (`gh auth status` prints `Logged in to github.com`).
+  <Step title="Authenticate with KHAL Gitea">
+    Use the internal Gitea credentials or SSH key from onboarding. For CLI checks:
 
     ```bash
-    gh auth login
+    tea login list
+    tea whoami
     ```
 
-    Git HTTPS requests will route through `gh auth git-credential`, so you never need to paste a personal access token into a dotfile.
+    For SSH remotes, register your public key in the internal Gitea UI before cloning.
   </Step>
 
-  <Step title="Clone with submodules">
+  <Step title="Clone the repo you are working on">
     ```bash
-    git clone --recurse-submodules https://github.com/khal-os/genie.git khal-os
-    cd khal-os
+    git clone <private-khal-gitea-repo-url>
+    cd <repo>
     ```
 
-    The clone target is named `khal-os` by convention — every guide in these docs assumes the workspace lives in a directory called `khal-os/`.
+    Use GitHub only for the public docs repo and the GitHub-hosted app-kit/desktop exceptions.
   </Step>
 
   <Step title="Bootstrap the workspace">
     ```bash
     ./init.sh
     ```
 
-    `init.sh` is the **single** bootstrap command. It fetches every sibling repo, aligns each submodule to its tracked branch, verifies the working tree, and prints role-specific next-step hints. It is idempotent — re-run it any time you pull the meta-repo or suspect your submodules drifted.
+    If the repo ships an `init.sh`, run it after cloning. Private app repos may instead use the generated app workflow from [FDE CLI quickstart](/dev/fde-cli-quickstart): `bun install`, `bun run build`, `bun run typecheck`, then `khal install ... --dry-run`.
 
     <Callout type="tip">
       Run `./init.sh --help` to see the available options, including `--dry-run` (preview actions) and `--verbose` (extra debug output).
@@ -60,7 +61,7 @@ KhalOS is developed as a workspace of repositories wired together by a meta-repo
 
 ## What you get
 
-After `init.sh` finishes, the workspace materializes every KhalOS repo so you can jump between the SDK, reference packs, and your own pack freely — without ever needing to clone a second time. You'll edit pack code in one directory, follow a symbol into the SDK in the next, and run everything from the same terminal.
+After cloning, keep the repo on its authoritative remote. For private app/platform work that is KHAL Gitea. For docs/app-kit/desktop exceptions that may still be GitHub. Do not publish private repo URLs, tokens, credential-helper output, or internal host details in public docs/issues.
 
 <CardGroup cols={2}>
   <Card title="Install dependencies" href="/getting-started/install-dependencies">
@@ -74,21 +75,19 @@ After `init.sh` finishes, the workspace materializes every KhalOS repo so you ca
 ## Troubleshooting
 
 <AccordionGroup>
-  <Accordion title="`gh: command not found`">
-    Install GitHub CLI from [cli.github.com](https://cli.github.com) and re-run `gh auth login`. The workspace does not support plain HTTPS with cached passwords — it expects `gh auth git-credential` to be wired up.
+  <Accordion title="Gitea clone fails">
+    Confirm your internal Gitea account, SSH key, or credential helper. Run `tea login list`, `tea whoami`, and `git ls-remote <private-khal-gitea-repo-url>` without pasting tokens into logs.
   </Accordion>
   <Accordion title="`init.sh` aborts on git version">
     Upgrade to git 2.30 or newer. Older git versions don't honor the submodule flags `init.sh` relies on.
   </Accordion>
   <Accordion title="I prefer SSH remotes over HTTPS">
-    Swap remotes after the first successful `init.sh`:
+    Use the SSH clone URL from the internal Gitea UI, then verify:
 
     ```bash
-    git remote set-url origin git@github.com:khal-os/genie.git
-    git submodule foreach 'git remote set-url origin $(git remote get-url origin | sed "s|https://github.com/|git@github.com:|")'
+    git remote -v
+    git ls-remote origin
     ```
-
-    Future `init.sh` runs will use SSH.
   </Accordion>
 </AccordionGroup>
 
@@ -99,6 +98,6 @@ After `init.sh` finishes, the workspace materializes every KhalOS repo so you ca
     pnpm + bun + the node versions your workspace actually needs.
   </Card>
   <Card title="Your first pack" icon="rocket" href="/getting-started/your-first-pack">
-    Scaffold a pack from the template and run it in the shell.
+    Scaffold an app with `khal new` and run the local proof loop.
   </Card>
 </CardGroup>
diff --git a/getting-started/your-first-pack.mdx b/getting-started/your-first-pack.mdx
@@ -14,7 +14,7 @@ A pack is a self-contained KhalOS app: a frontend React package plus an optional
 `@khal-os/app-kit` ships the public `khal` CLI. Install it from npmjs, verify the version/template bundle, then scaffold locally.
 
 ```bash
-npm install --registry=https://registry.npmjs.org/ --global @khal-os/app-kit@latest
+npm install --global @khal-os/app-kit@latest
 khal --version
 khal new --list
 ```
@@ -101,7 +101,7 @@ khal install . --target dev --dry-run --json
 The dry-run validates source shape, `khal-app.json`, env declarations, target resolution, and the command that would perform the real install. It performs no mutation. For remote app repos, use an explicit branch:
 
 ```bash
-khal install https://github.com/<org>/<app-repo> --branch dev --target dev --scope shared --dry-run --json
+khal install <private-khal-gitea-repo-url> --branch dev --target dev --scope shared --dry-run --json
 ```
 
 ## 6. See it in the shell

diff --git a/release/customer-install.mdx b/release/customer-install.mdx
@@ -23,13 +23,13 @@ Do not hand off a pack npm package name. App repos are installed from git; `@kha
 The customer/admin UI and CLI are two views of the same install contract. The FDE dry-run shape is:
 
 ```bash
-khal install https://github.com/<org>/<app-repo> --branch <branch> --target dev --scope shared --dry-run --json
+khal install <private-khal-gitea-repo-url> --branch <branch> --target dev --scope shared --dry-run --json
 ```
 
 A real authorized install omits `--dry-run`:
 
 ```bash
-khal install https://github.com/<org>/<app-repo> --branch <branch> --target dev --scope shared
+khal install <private-khal-gitea-repo-url> --branch <branch> --target dev --scope shared
 ```
 
 See [FDE CLI quickstart](/dev/fde-cli-quickstart) for login and troubleshooting.

diff --git a/release/publish-your-pack.mdx b/release/publish-your-pack.mdx
@@ -46,7 +46,7 @@ Customize behavior by editing these workflows in your pack repo — they're your
 Before handoff, prove the exact git source/ref with the public CLI:
 
 ```bash
-khal install https://github.com/<org>/<app-repo> --branch <branch> --target dev --scope shared --dry-run --json
+khal install <private-khal-gitea-repo-url> --branch <branch> --target dev --scope shared --dry-run --json
 ```
 
 For the full CLI setup and login flow, see [FDE CLI quickstart](/dev/fde-cli-quickstart).