> ## Documentation Index
> Fetch the complete documentation index at: https://xanots.docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start here

> Four situations people arrive in — building something new, joining a team, migrating an existing workspace, or new to git — and the shortest honest path through the docs for each.

The rest of these guides are organized by *concept*. This page is organized by **situation** —
find yours, do the three or four things it names, and skip everything else until you need it.

<Columns cols={2}>
  <Card title="Building something new" icon="rocket" href="#building-something-new">
    Alone, from an empty folder.
  </Card>

  <Card title="Joining a team" icon="users" href="#joining-a-team">
    The repo and the workspace already exist.
  </Card>

  <Card title="Migrating a workspace" icon="cloud-arrow-down" href="#migrating-an-existing-workspace">
    Built in the UI, and you want it as code.
  </Card>

  <Card title="New to git" icon="graduation-cap" href="#new-to-git">
    Read this before the team pages.
  </Card>
</Columns>

## Building something new

Working alone, nothing exists yet. **You can ignore almost everything** — no branches, no pull
requests, no CI.

<Steps>
  <Step title="Get something live">
    Follow the [Quickstart](/guides/quickstart) — four commands, and you have a running backend
    and frontend.
  </Step>

  <Step title="Learn the two-command loop">
    `xanots deploy` pushes to a disposable [ephemeral](/guides/glossary) you can break freely.
    `xanots release` promotes to your real workspace. Iterate on the first; use the second when
    you mean it.
  </Step>

  <Step title="Form one habit">
    `xanots release --dry-run` before any real release. It prints exactly what would change and
    sends nothing — including any table column your code no longer defines, which takes its
    data with it.
  </Step>
</Steps>

**Come back for:** [Working outside git](/guides/workflow-repo#when-you-have-to-work-outside-git)
when you first edit something in the Xano builder, and [Git, locks &
merges](/guides/git-and-merges) when a second person joins.

<Note>
  You do not need branches or pull requests to use XanoTS alone. Committing straight to `main` is
  a legitimate way to work — most of what the team pages describe exists to solve problems you do
  not have yet.
</Note>

## Joining a team

The repo exists and so does the workspace. The one thing to establish before you touch
anything:

<Steps>
  <Step title="Ask where the truth lives">
    **The repo, or the workspace?** It decides how you contribute, what review means, and what
    a merge is. [Development workflows](/guides/development-workflows) explains both in two
    minutes.

    If nobody knows, look: a committed `xano.lock` and a CI job running `xanots release` means
    the repo is authoritative.
  </Step>

  <Step title="Read your team's flow, not both">
    [Repo is the truth](/guides/workflow-repo) — you work in git and open pull requests.

    [Workspace is the truth](/guides/workflow-workspace) — you pull a copy, push it back as a
    Xano branch, and promoting the branch is the merge. **Still in development**, so most teams
    are on the first one today.
  </Step>

  <Step title="Sign in and confirm where you are pointed">
    ```bash theme={null}
    xanots login
    xanots workspace details     # is this the workspace you expected?
    ```

    One credential addresses exactly one workspace — there is no `--workspace` flag.
  </Step>

  <Step title="Deploy to your own ephemeral before anything else">
    ```bash theme={null}
    xanots deploy ./xano/index.ts
    ```

    Everyone gets their own, so this cannot affect a teammate or production. It is the safest
    possible first command.
  </Step>
</Steps>

**Then read** the [PR review checklist](/guides/git-and-merges#reviewing-a-xanots-pull-request)
— it covers the things a normal code review misses, which is most of what a XanoTS reviewer
needs to know.

## Migrating an existing workspace

You built it in the UI and want it as code. **One step here is irreversible if you skip it**,
so do these in order.

<Steps>
  <Step title="Pull it down">
    ```bash theme={null}
    xanots init my-app --from workspace
    cd my-app && git init && git add -A && git commit -m "adopt workspace"
    ```
  </Step>

  <Step title="Read two files before you go further">
    `xano/README.md` lists anything that did not translate cleanly. `xano/workspace.ts` carries
    your environment variable **values** inline — move real secrets out before that commit
    reaches a shared repo.
  </Step>

  <Step title="Capture the identities — do not skip this">
    ```bash theme={null}
    xanots workspace export --path live.json
    xanots lock import live.json --entry=xano/index.ts --yes
    git add xano.lock && git commit -m "pin live identities"
    ```

    <Warning>
      The engine gave your existing objects random identities, and nothing in your code can
      re-derive them. Without this step your first release matches nothing and **duplicates every
      object** instead of updating it.
    </Warning>
  </Step>

  <Step title="Decide what the workspace is now">
    [Repo is the truth](/guides/workflow-repo) is the flow to use today, and it works even if
    some people still edit in the Xano builder — those edits get [pulled back into
    git](/guides/workflow-repo#when-you-have-to-work-outside-git) rather than lost.

    [Workspace is the truth](/guides/workflow-workspace) is the better long-term fit for a
    builder-led team, but the branch releases it depends on are still in development. Read it to
    plan for it; do not adopt it as your process yet.
  </Step>
</Steps>

Full detail: [Pulling an existing workspace](/guides/codegen).

## New to git

XanoTS does not require git — you can `deploy` and `release` without ever making a commit, and
[building something new](#building-something-new) above works fine that way.

You need git the moment **a second person** is involved, because it is how two people change
the same thing without overwriting each other.

<Steps>
  <Step title="Learn the eight commands">
    [Git, locks & merges](/guides/git-and-merges) opens with a collapsible primer covering
    exactly the commands these flows use, what a branch is, and how a pull request works — plus
    both the GitHub and GitLab CLIs.
  </Step>

  <Step title="Then learn the one XanoTS-specific part">
    Same page: `xano.lock` is a file XanoTS maintains that pins your objects' identities. You
    commit it like any other file, and the only unusual thing is what to do when it conflicts
    (take both sides, re-run `xanots export`).
  </Step>
</Steps>

For git itself, the [GitHub "Hello World"
guide](https://docs.github.com/en/get-started/quickstart/hello-world) is ten minutes and
[Learn Git Branching](https://learngitbranching.js.org) teaches the branch model interactively.

## When something breaks

[Troubleshooting](/guides/troubleshooting) maps the CLI's refusals and exit codes to causes and
fixes. Two worth knowing before you need them:

* **A release that refuses is protecting you.** Dropped columns, unscoped prunes and unreadable
  workspaces all stop and ask rather than proceeding.
* **A rollback is just releasing an earlier commit** — but it does **not** bring back data from
  a dropped column. See [when a release goes
  wrong](/guides/workflow-repo#when-a-release-goes-wrong).

## Unfamiliar word?

[Glossary](/guides/glossary) — instance vs workspace vs environment, ephemeral vs branch,
`deploy` vs `release`, bundle, guid, canonical, and the pairs that are easy to confuse.