# Recipe: onboard a client repository

**The scenario:** a client hands you a repository. You have never run it, you do not know what is in its history, and you need to be delivering against it this week — without their credentials ending up somewhere they should not be.

This recipe is the safe path, in the order the risks actually arrive.

## Prerequisites

- A hlix workspace and an API key
- The client's repository checked out locally
- Agency `owner` or `admin` if you will also connect GitHub

## The recipe

1. **Look before you upload.** The first command is not an import.

   ```bash
   cd path/to/client-repo
   hlix import . --dry-run
   ```

   Read three things in the report: **history findings**, **protected files**, and **quarantined resources**. A client repository is exactly where a committed `.env` from two years ago shows up.

2. **Deal with what the scan found — do not override it.**

   If history findings appear, the credential is in the Git history and anyone with that history can recover it. `--history preserve` uploads the history *despite* the findings; it does not remove them. Rotate first, with the client, then re-scan.

   ```bash
   hlix import . --dry-run --history abort-on-findings
   ```

   Expected result: no blocking findings. That is the gate for continuing.

3. **Import for real.**

   ```bash
   hlix import . --name "Acme — storefront"
   ```

   Expected result:

   ```text
   Imported Acme — storefront
   Project ID: 6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41
   Revision: 1
   ```

   Protected files travelled the encrypted path and are out of the Git bundle. Quarantined resources — any `AGENTS.md`, skill, or `.mcp.json` the client's repo carried — are preserved but **inert**.

4. **Decide what you trust.** The client's repository may contain agent instructions written by someone else. They do nothing until you activate them, and you should read them before you do.

   ```bash
   hlix agent import AGENTS.md --name "Acme builder"
   ```

   Skip this step entirely if you would not hand those instructions to a contractor.

5. **Attach it to the client account** in the dashboard, under **Customers**, so the project appears in that client's grouping and their portfolio rolls up correctly.

6. **Ship one small thing first.** Not the big refactor. Pick a change whose correctness you can judge at a glance, so the first review tells you whether the setup is right rather than whether the change is right.

   Start the run from the dashboard, or over the API:

   ```bash
   curl -sS -X POST "$HLIX_BASE_URL/v1/api/projects/$PROJECT_ID/start" \
     -H "x-api-key: $HLIX_API_KEY" \
     -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
     -H 'content-type: application/json' \
     -d '{"brief":"Add a health endpoint at GET /healthz returning 200 with the build SHA, and cover it with a test."}'
   ```

7. **Read the evidence, not the summary.**

   ```bash
   hlix tasks list
   hlix tasks review <task-id>
   ```

   The `files[].patch` is the diff read back from the repository host — an observation, not the agent's account of itself.

## What this buys you

- The client's secrets never entered a commit, and you found the historical ones before they became your problem.
- Someone else's agent instructions did not silently start steering your delivery.
- The first change was small enough that a bad result told you about your *setup*.
**`--yes` is not a way past a blocker:** In CI you will want `--yes`, and it is the right flag for approving a reviewed upload. It does **not** override history findings, unsafe paths, integrity failures, or size limits. If an import is blocked, the blocker is the message — not the flag.

## If the recipe stalls

- `scan_blocked` on a repo the client swears is clean — the blocker list names each finding. See [If the scan blocks the import](/cli/import/#if-the-scan-blocks-the-import).
- `already_imported` — the folder is bound from a previous attempt. Use [`hlix push`](/reference/cli/sync/), or delete the cloud project and re-import.
- The first task never runs — a task must come from a cycle. A project run creates them; a standalone task does not execute. See [Tasks](/running/tasks/).
- Review evidence says it cannot verify the branch — the project has no connected remote yet. Connect GitHub, or read the downloadable workspace archive instead.

## Next steps

[Import trust model](/security/trust-model/)
  [Parallel cycle delivery](/guides/recipes/parallel-cycle-delivery/)
  [Reviewing output](/running/review/)
  [GitHub](/integrations/github/)