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

# Project setup

> Shared scripts, prompts, and workspace defaults in .archductor/settings.toml.

Shared project settings live at `.archductor/settings.toml` in the repository
root. In product terms these are project-level settings, because one Archductor
project wraps one repository.

Commit shared `.archductor` files when teammates or another machine should get the
same setup. Keep `.archductor/settings.local.toml` out of version control — that
is where machine-local overrides and secrets belong.

<Warning>
  Every `env_file_refs` path is required when a workspace launches. Remove the
  block if the file does not exist, or commit or create the referenced `.env`
  file. A missing reference blocks the launch.
</Warning>

## Example settings

```toml .archductor/settings.toml theme={"dark"}
"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"

file_include_globs = """
.env*
config/*.local.json
"""

env_file_refs = """
.env
"""

spotlight_testing = false

[scripts]
setup = "pnpm install"
run = "pnpm dev --port $ARCHDUCTOR_PORT"
archive = "./script/workspace-archive.sh"
test = "cargo test --workspace"
lint = "cargo clippy --workspace"
```

`$ARCHDUCTOR_PORT` is the stable per-workspace port. Use it in your `run` script
so parallel workspaces do not fight over a port.

## What setup should cover

Setup and run and archive scripts, copied files, environment variables, prompts,
providers, and Git behavior should all be visible and editable from the product —
not buried in terminal-only steps.

* **`file_include_globs`** — gitignored files to copy into each new working tree.
  Only gitignored files are copied; generated files and dependency installs are
  not.
* **`env_file_refs`** — env files a workspace requires at launch.
* **`[scripts]`** — `setup`, `run`, `archive`, `test`, `lint`.
* **Workspace defaults** — base branch, branch prefix, working directory, port
  block size, default visible tab.
* **Prompt packs** — config bootstrap seeds `.archductor/prompt-packs/default.toml`
  for new projects.

## Local overrides

```toml .archductor/settings.local.toml theme={"dark"}
# Machine-local. Do not commit.
```

Anything you do not want teammates to inherit — absolute paths, personal API
endpoints, per-machine port choices — goes here.