> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL.

# Workspace

A Khotan workspace is a **monorepo**: one GitHub repo per organization, using Bun workspaces and Turborepo. Apps live under `apps/deployments/`; pipelines live under `apps/pipelines/`. The repo root holds shared agent skills and instruction files. Per-app guidance lives in each subdirectory's own `AGENTS.md` / `CLAUDE.md`. See [Concepts](/basics/concepts/) for the layout.

## Check the checkout

```sh
khotan workspace check
khotan workspace check --json
```

The command fetches `origin/main` and compares it with `HEAD`. It updates
remote-tracking metadata only. It never merges, rebases, resets, stashes, or
changes worktree files.

- `synced` means `HEAD` contains the same commits as `origin/main`.
- `ahead` means local commits are not on `origin/main`. The command warns.
- `behind` means `origin/main` has commits missing locally. The command blocks.
- `diverged` means both sides have unique commits. The command blocks.
- `unverifiable` means the remote is missing or cannot be fetched. The command
  blocks.
- `dirty: true` means tracked or untracked worktree changes exist. The command
  warns unless another state blocks.

In a workspace with `.env.khotan.local`, catalog write and destructive commands
run this check automatically. If the check blocks, update or reconcile the
checkout yourself, then run it again. Khotan never changes local Git work.

To recover:

- For `behind`, review the remote commits and update the checkout. Use
  `git pull --ff-only` only when the worktree is safe.
- For `diverged`, choose and perform the repository's normal merge or rebase
  workflow.
- For `dirty`, commit, stash, or keep the changes deliberately.
- For `ahead`, push the commits when they are ready.
- For `unverifiable`, restore the `origin` remote or GitHub access, then retry.

## Status

```sh
khotan status           # topology: apps, pipelines, databases
khotan status --write   # refresh a committable WORKSPACE.md from live data
```

Use `khotan status` to see which subdirectory maps to which app or pipeline, which database it uses, and which repo it deploys from.

## Clone

`khotan apps get <appId>` and `khotan pipelines get <pipelineId>` return `repo.clone` (HTTPS, SSH, GitHub CLI) and `repo.subdirectory`. Databases live in the same repo. See [Concepts](/basics/concepts/).

## Do not scaffold at the root

Each app lives in its own subdirectory. **Do not run app scaffolders (for example `khotan-data init`) at the repo root.** `cd` into the app's subdirectory first.

## Next

See [commands](/cli/commands/) for the catalog-derived surface, and [output](/cli/output/) for `--json`.