ARCADIA-Studio/docs/source-cli.md

# Source CLI

Use `arcadia` to check or update local `.arcadia` projects without opening Studio
or starting a server. Pass the entry file explicitly; its relative include paths
resolve from their containing source files.

Build with `cargo build --locked -p oa-cli --bin arcadia`. The resulting command
is `target/debug/arcadia.exe` on Windows or `target/debug/arcadia` on Linux unless
your Cargo configuration chooses another target directory. A workspace release
build also includes it. Use the platform's usual executable path prefix when
running these examples.

```sh
arcadia check project.arcadia
arcadia check project.arcadia --json
arcadia stabilize project.arcadia
arcadia stabilize project.arcadia --write
arcadia rename-alias project.arcadia old_alias new_alias
arcadia rename-alias project.arcadia old_alias new_alias --write --json
```

`lint` is an alias for `check`. Checks accept incomplete engineering models with
warnings; syntax errors and structural violations fail. Located diagnostics
refer to the named file and coordinate space. Line and column numbers are
one-based and columns count Unicode scalar values; byte ranges are half-open
UTF-8 offsets.

`stabilize` previews missing persistent identities and any supported source
migration. `rename-alias` changes one existing global alias and its typed
references while preserving comments, strings and unrelated source. Pass alias
names without `@`. The command does not rename an element's display name.

Both editing commands preview by default. Human output writes unified file
diffs to stdout and diagnostics to stderr. `--json` writes one versioned report
with diagnostics, migration information, exact before/after text for every
changed file, diffs and the write result. Unchanged files are not included in
that report. They are still checked for conflicts before a write.

Add `--write` to save the candidate prepared by that invocation. Even an empty
diff checks the captured files and pending-save state before returning. A failed
write reports `written: false` and retains its proposed diff. This does not
guarantee rollback; the reported conflict or recovery outcome determines the
next step. A pending save
requires explicit recovery through the existing project recovery workflow;
the CLI does not recover it automatically.

Missing IDs in a separate earlier preview remain provisional. A later command
may allocate different IDs until you save them. This CLI does not persist a
review plan for later application. It does not canonicalize the whole project
or delete detached files. Source versions 3–7 use the core's supported migration
rules; invalid source is not rewritten.

| Exit code | Meaning |
| --- | --- |
| 0 | Valid check or successful preview/write; warnings may remain |
| 1 | Invalid source or refused semantic alias change |
| 2 | Invalid command arguments |
| 3 | File/path, conflict, pending-save or output failure |

Admission bounds match the desktop: 256 files, include depth 32, 1024 include
edges, 64 MiB total UTF-8, 100,000 graph objects, 250,000 records and 500,000
ordered references. `arcadia --help` lists the commands and bounds. These limits
are not a claim of interactive performance at the maximum project size.

For the notation itself, start with [the text-first examples](../examples/text-first/README.md)
and the [language contract](language.rst).


## Read-only mixed source8 checking

```sh
arcadia check-mixed path/to/main.arcadia --json
```

Use `check-mixed` for source8 containing ordinary declarations and typed analysis
(quantity kinds, units, calculations, properties, checks and cases). Every
project, ordinary declaration, typed definition and scoped parameter must have
an explicit UUID. This command does not migrate older headers, allocate UUIDs,
format, preview edits or save. `--write` is a usage error. Existing `check`,
`lint`, `stabilize` and `rename-alias` retain their ordinary-source behavior.

The loader discovers actual includes with the source grammar and existing
portable-path, regular-file, bounded-read and pending-journal checks. It captures
original bytes, runs a bounded discovery syntax pass, then checks the complete
borrowed bundle in a separate bounded verification pass. A discovery diagnostic
prevents complete verification; the first mixed syntax/work failure stops
further discovery parsing. Both passes derive limits from the same CLI policy;
numeric work is bounded per pass, not once across the whole command. Logical
producer limits are not a bound on all allocations or process memory.

The format-1 JSON envelope uses operation `check-mixed`, status `checked` or
`invalid` for completed source checking, and existing `rejected` for direct disk
errors. `changes` is empty, `written` is false, `identities_to_stabilize` is zero,
`migration` is null and `notes` is empty. Located diagnostics refer to original
`input` bytes, with half-open UTF-8 byte spans and one-based Unicode-scalar
line/column coordinates. Direct filesystem failures use the existing operation
coordinate space. Engineering warnings permit exit 0; invalid source/semantics
exit 1, usage exits 2, and disk/path/missing-file/pending-journal failures exit 3.
Invalid UTF-8 discovery diagnostics retain the existing source-error exit 1.

Human output goes to stderr and ends with `checked: mixed source8 check; no files
changed` on success, after any warnings. No source bytes or directory entries
are written, and pending saves are never recovered implicitly. Checking captured
bytes does not establish an atomic multi-file snapshot against concurrent writers.
This command provides validation only; mixed editing, adoption, GUI and history
integration remain outside this interface.