---
name: code-repository-local-setup
description: Set up a newly created or existing initialized Main Sequence CodeRepository as a verified local checkout and establish local authentication through a backend-issued MCP-to-CLI handoff or an injected runtime credential. Use after CodeRepository creation, when preparing one locally, or when its local authentication must be refreshed.
---

# Main Sequence CodeRepository Local Setup

Use this skill after creating a Main Sequence CodeRepository or when a user asks
to set up an existing CodeRepository in the caller's local workspace.

The MCP server supplies authenticated platform state and repository-access
operations. The calling host owns the local filesystem, Git, SSH private keys,
credential store, and editor. The external agent selects and sequences the
workflow; the MCP server does not clone repositories or write local files.

## Completion Contract

Report local setup as complete only when all of the following are true:

- `code_repository.get` returns the CodeRepository and its lightweight
  `{uid, repository_branch}` branch selector;
- `code_repository_branch.get` confirms that the selected CodeRepositoryBranch has
  `provisioning_status=READY` and the compatible `is_initialized=true` projection;
- `github_repository_binding.get` confirms that the CodeRepository's GitHubRepositoryBinding has a
  nonempty clone URL;
- the user confirmed the fully resolved canonical checkout path;
- the selected local directory is either a verified checkout of that exact
  repository or a newly completed clone;
- repository access was verified using a caller-owned SSH private key;
- `.env` contains the Main Sequence endpoint; it contains no repository or
  branch identity variable, because canonical local identity is resolved from
  the verified Git checkout, and no credential, because the session is kept in
  the machine's credential store and not in the checkout (the entries an
  older CLI writes there itself are the one exception, described below);
- local CLI/runtime authentication was established through either the
  backend-issued MCP handoff or the existing injected runtime-credential lane,
  and the CLI reports a working session, without returning credentials through
  MCP or model-visible output;
- `.env` is excluded from Git; and
- the repository's own `AGENTS.md` and relevant skills have been read before
  implementation begins.

A successful clone without working local authentication is partial setup, not
completed setup. Preserve the checkout and report the remaining authentication
step rather than deleting successfully cloned source.

## Preserve The Boundary

The skill owns the platform-aware sequence, readiness checks, safe repository
identity rules, local-authentication contract, verification, and
handoff.

Git branch discovery in this skill applies only to a genuine caller-owned local
checkout. A deployed JobRun, CodeRepository Executor, or runtime ResourceRelease must
use the backend-issued `runtime_code_repository_context.code_repository_branch_uid`; it must not
inspect Git, infer a branch from its working directory, or persist a competing
CodeRepositoryBranch selector.

Do not:

- ask the MCP server to read or write a caller-local path;
- send an SSH private key, access token, refresh token, runtime credential
  secret, `.env` content, or local absolute path in an MCP tool argument;
- request or expose the MCP Authorization header through a tool;
- print, summarize, copy to chat, or commit credential values;
- write, copy, or move a credential into `.env` or any other file of the
  checkout;
- infer initialization merely because `code_repository.create` returned;
- silently ignore deploy-key registration failures;
- overwrite an existing directory or repoint an existing Git remote;
- recursively scan a home directory to find a checkout;
- treat `.env` as repository-owned documentation; or
- require Python, the Main Sequence SDK, or the Main Sequence CLI merely to
  inspect CodeRepository readiness, register the deploy key, or clone. A runnable
  SDK checkout may then use its installed CLI for the approved authentication
  handoff.

## Resolve And Wait For The CodeRepository

1. Keep the CodeRepository UID returned by `code_repository.create`, or resolve an
   existing CodeRepository with `code_repository.list`, `code_repository.search`, and `code_repository.get`.
2. Read the CodeRepository with `code_repository.get`. Its `branches` collection is a
   selector only and contains exactly `uid` and `repository_branch`. Do not
   expect readiness, configuration, or repository fields on these items.
3. Select one exact branch. After creation, refresh the branch collection in the
   requested bootstrap Environment and resolve by parent CodeRepository UID plus exact
   Environment. Omission of bootstrap context yields only `main`; a non-main bootstrap
   may also create a hidden production `main`, so never pick the first returned branch.
   For an existing repository use the branch explicitly selected by the user or calling
   flow. Do not infer a default, entry, oldest, or current branch from collection order.
4. Read the selected branch with `code_repository_branch.get`. Keep its UID only for
   the remote setup operations that explicitly require a CodeRepositoryBranch.
5. Read the CodeRepository's `github_repository_binding_uid` with `github_repository_binding.get`.
   `git_ssh_url` and `git_repo_url` belong only to GitHubRepositoryBinding; never treat a
   clone URL as CodeRepositoryBranch state.
6. Branch on `provisioning_status`. For `CREATING`, wait and retry
   `code_repository_branch.get` with a bounded interval. For `FAILED`, stop
   polling and report `provisioning_error_code`, `provisioning_error_detail`,
   and `provisioning_job_run_uid`; do not invoke the DRF-only retry action or
   retry `code_repository.create`. Continue only for `READY`, whose compatible
   `is_initialized` projection must be true. If the GitHubRepositoryBinding
   clone URL is not ready, retry `github_repository_binding.get`.
7. If initialization remains `CREATING` beyond the user's available working
   window, report the CodeRepository UID, selected branch name and UID, and
   current provisioning state plus the linked setup JobRun UID. Do not invent a
   repository URL or continue with a partial provider result.

Repository initialization is platform state. Polling it is caller behavior;
it is not an MCP task or subscription.

## Select A Safe Local Destination

Treat the user-selected path as the organization-independent Main Sequence
development base. Default that base to:

```text
~/mainsequence
```

Resolve the authenticated user's Main Sequence organization name and normalize
it as a filesystem-safe organization slug: lowercase it, replace unsupported
characters with `-`, and trim leading or trailing `-`. Do not use a GitHub
organization in place of the user's Main Sequence organization.

Always append the organization slug and `code-repositories` directory to the selected
base, including when the user chooses a custom base. Resolve the final checkout
as:

```text
<base>/<organization-slug>/code-repositories/<safe-code-repository-name>-<code-repository-uid>
```

For example, the default base resolves to:

```text
~/mainsequence/<organization-slug>/code-repositories/<safe-code-repository-name>-<code-repository-uid>
```

If the user selects `/work/mainsequence`, resolve the checkout under
`/work/mainsequence/<organization-slug>/code-repositories/`; never place the code repository
directly under `/work/mainsequence` and never omit the organization segment.

Show the user the fully resolved final checkout path and ask for confirmation
before creating directories, generating a key, registering a deploy key, or
cloning. If the host cannot resolve the organization name from its authenticated
profile, ask the user to identify it before constructing or confirming the
path. Do not fall back to a `default` organization directory.

The directory shape is a local convention, not a platform identifier. Use the
CodeRepository UID for aggregate operations and deploy-key registration. Use
the selected CodeRepositoryBranch UID only for explicit branch reads and clone branch
selection. After checkout, local CLI workflows derive branch context from Git
and must not require users to manage or persist that UID.

Before creating anything:

1. Inspect only the confirmed organization code-repositories root, resolved target, and
   current workspace.
2. If a candidate checkout exists, read its `origin` URL and resolve its
   authenticated CodeRepository context without printing credential values.
3. Reuse it only when repository origin and CodeRepository identity agree.
4. Stop on an occupied nonrepository directory, a different origin, or a
   conflicting CodeRepository identity or repository branch. Do not delete, rename, or
   overwrite it automatically.

## Establish Repository Access

Generate or reuse a code-repository-specific SSH key locally. Prefer Ed25519 when the
host supports it. The private key never leaves the host.

Call:

```text
code_repository.add_deploy_key
```

with:

- `code_repository_uid`: the public CodeRepository UID;
- `key_title`: a stable human-readable local host or harness identity; and
- `public_key`: only the OpenSSH public key text.

Adding a deploy key needs `code-repositories.add_deploy_key`: repository
editor or owner, or editor of one of the repository's branches, held directly,
through a Team or through an Organization Project. A branch or Project policy
also makes the repository appear in `code_repository.list` and
`code_repository.search`, without reaching its other branches.

The tool delegates to the CodeRepository DRF action and returns an empty
object on canonical success. It does not return repository credentials or
provider metadata. Treat any MCP/DRF error as an incomplete access step and
surface it before cloning. Even after success, verify access by cloning or by a
nonmutating Git connection check because the external Git provider remains the
source of truth for repository acceptance.

Clone the GitHubRepositoryBinding `git_ssh_url` using the selected private key through
the host's local Git facilities, then check out the selected
`repository_branch`. Do not read a clone URL from CodeRepositoryBranch and do not place
the private-key content in a generated command. If a failed clone created a new
incomplete target directory, remove only that exact new directory after
verifying it was created by the current attempt. Never remove a pre-existing
directory.

After cloning, verify that `origin` identifies the expected GitHubRepositoryBinding and
that `git branch --show-current` equals the selected branch. Do not repoint a
remote or silently select another branch merely to make a mismatch disappear.

## Establish Local Authentication

The session belongs to the machine, not to the checkout. The CLI keeps one
session per backend in the operating system's credential store, the SDK reads
it when it is imported, and one login serves every checkout on that machine.
The checkout's `.env` holds the Main Sequence endpoint and no credential.

Use the CLI the checkout has. A Python repository has `mainsequence` in its
environment. A Vite application has `command-center-sdk` once its dependencies
are installed, run as `npx command-center-sdk`. Both CLIs read and write the
same machine session and name these commands the same, so a session made with
either serves both kinds of checkout.

Do not copy credentials out of the MCP host's OAuth store. The supported normal
user lane creates a separate tracked CLI session through a short-lived PKCE
handoff:

1. On the machine that owns the checkout, run the handoff login of its CLI.
   In a Python repository:

   ```text
   mainsequence login --mcp
   ```

   In a Vite application:

   ```text
   npx command-center-sdk login --mcp
   ```

2. Keep the command running. It sends only PKCE state and challenge to
   `POST /auth/mcp/cli-handoff/start/`. The backend creates the grant and
   returns its exact callback URI; the CLI never invents or supplies a
   localhost redirect URI.
3. Read the JSON tool request printed by the command and call exactly
   `auth.cli_authorize` with its `handoff_uid`. Do not alter or reuse a handoff
   UID from another process.
4. The waiting CLI polls the backend-issued callback with its private PKCE
   verifier. After authorization, the callback returns the normal tracked JWT
   pair directly to the CLI, which saves it in the machine's credential store.
   Neither token enters the MCP tool result or model output.
5. Confirm the session from inside the checkout:

   ```text
   mainsequence refresh-token
   ```

   In a Vite application the same command is
   `npx command-center-sdk refresh-token`. The command takes no path. It renews the saved session, reports the backend,
   the user, and the expiry, and prints no token value. When the `.env` of the
   directory it runs in still holds an access token, a refresh token, or a
   runtime credential from an earlier setup, it removes those entries and names
   them. A nonzero exit means there is no working session; report its message.

A machine that already holds a working session for this backend, made with
either CLI, needs no new handoff: `refresh-token` succeeds there. Start the
handoff when it fails.

A CLI released before the machine session has no top-level `refresh-token` and
answers `No such command`. It keeps the session in the checkout instead. With
such a CLI, run `mainsequence code-repository refresh-token --path <checkout>`,
which writes these entries into `.env` itself:

```text
MAINSEQUENCE_ACCESS_TOKEN
MAINSEQUENCE_REFRESH_TOKEN
MAINSEQUENCE_ENDPOINT
```

Those entries are that CLI's own output. Never add, copy, or edit them.

A `command-center-sdk` released before the machine session has no `login` and
answers `Unknown command`. It keeps no session. When the machine also has the
`mainsequence` CLI, make the session with that one. Otherwise preserve the
checkout and report local runtime authentication as pending, and that the
checkout needs a Command Center SDK that has `login`.

For a deployed Main Sequence Harness Agent runtime, do not use the handoff to convert its
access-only principal into a refresh-backed user session. Its deployment
already injects the credential ID and `MAINSEQUENCE_RUNTIME_IDENTITY_TOKEN_FILE`;
the SDK reads the rotating projected-token file for each exchange. The user never authors that
auth mode, credential, CodeRepositoryBranch UID, repository branch, or
Organization Environment UID. Run ordinary `mainsequence login`, then
`mainsequence refresh-token`; the CLI uses its current noninteractive runtime
exchange and writes nothing into `.env`. Hosted projected authentication needs
at least `mainsequence` 9.0.8 or `ms-tau-sdk` 1.4.0; later request-identity and
delegation features require their own compatible releases. An older hosted
client must be upgraded and the image rebuilt. The legacy local CLI fallback
above does not apply to a hosted runtime: bootstrap-secret exchange is removed.
See `resource-release` Runtime authentication and recovery for errors.

Do not combine session-refresh and runtime-credential modes. Do not use
`mainsequence login --mcp --export`, manual token arguments, an MCP tool that
returns credentials, or the inbound MCP bearer as a substitute for the
handoff. A manually configured access token without refresh or durable runtime
credentials may permit the current MCP session, but it cannot provide durable
local SDK authentication. Report that limitation instead of claiming
completion.

The checkout's `.env` is not a credential store:

1. never write, copy, or move a token or a runtime credential into it;
2. never print it or return it to the model, and verify presence by key name
   only;
3. leave every unrelated entry as it is; and
4. let `mainsequence refresh-token` remove the credential entries an earlier
   setup left there, rather than editing them by hand.

Later authentication refresh is the same `refresh-token` of the checkout's CLI.
It uses the CLI's saved session or an already backend-injected runtime-credential
exchange. It never turns user-authored environment variables into deployed
runtime context; authenticated backend response state is required. Refresh is
not an MCP tool and does not expose credential values to the model.

A local tool that cannot read the credential store obtains a short-lived access
token from `auth token` of either CLI. That command exists for programs. Do not
run it to read a token into the conversation.

Verify that `.env` is ignored by the repository. If it is not ignored, stop and
ask for approval to correct the repository ignore policy: an older CLI and
other local tools may write secrets there.

If the local machine does not have the CodeRepository CLI/runtime needed to
execute the repository, preserve the verified checkout and report local runtime
authentication as pending. Do not work around that limitation by adding a
token-export tool or reading the MCP client's credential store.

## Verify And Hand Off

Verify without revealing sensitive values:

- CodeRepository identity and lightweight branch selection from `code_repository.get`;
- selected CodeRepositoryBranch UID, `provisioning_status`, linked setup JobRun
  UID, failure fields, and compatible `is_initialized` projection from
  `code_repository_branch.get`;
- clone URL and repository identity from `github_repository_binding.get`;
- exact Git `origin` agreement;
- current Git branch agreement with the selected `repository_branch`;
- clean repository identity and expected checkout root;
- `.env` presence, Git exclusion, and the endpoint entry, by key name only;
- a working local session: `mainsequence refresh-token` exits zero, or a
  nonsecret authenticated platform check succeeds through the selected local
  authentication mode; and
- repository instructions and existing user changes.

Then route work according to intent:

- use the relevant repository or SDK execution skills for accepted MetaTable,
  TimeIndexTableUpdater, job, API, CLI, code-repository-to-agent, or static-site components;
- use `code-repository-to-agent` only when the CodeRepository itself must become a coding
  agent; and
- use an installed SDK's `code-repository-maintenance` skill for SDK-version-specific
  `.venv`, SDK, managed-skill, and Git publication workflows when that SDK is
  present.

The interface-neutral local setup does not depend on that optional SDK lane.

## Report Partial Failures Precisely

Identify the last completed boundary and preserve safe completed work:

- initialization `CREATING`: no local changes required; report the linked setup
  JobRun and bounded-wait result;
- initialization `FAILED`: stop polling, preserve provider/platform state, and
  report the stable error fields and linked setup JobRun for an authorized
  human to inspect or explicitly retry through DRF;
- deploy-key failure: local key may exist, repository not yet accessible;
- clone failure: remove only a new incomplete clone created by this attempt;
- local authentication unavailable: preserve the verified checkout and
  report local runtime authentication as pending;
- `.env` validation failure: do not print the file or secret values; and
- repository-instruction failure: preserve setup and report the missing or
  invalid repository-owned contract.

Never rerun `code_repository.create` or the entire setup workflow blindly after a
partial failure.