docs: capture the empty [workspace] table gotcha for nested project crates

A project crate that path-depends on the engine and lives under the engine
repo (common during authoring) is rejected by cargo unless its Cargo.toml
carries an empty [workspace] table. Surfaced repeatedly by the cycle-0006 and
cycle-0007 fieldtests as a non-obvious onboarding one-liner.

Document it on the consumer-facing surface (project-layout, the "A project
repo" section) so a nested-project author can predict and fix it. The aura new
scaffolder will emit the line once it exists (folds into the CLI work); the
docs capture closes the actionable half now.

closes #9
This commit is contained in:
2026-06-04 17:47:45 +02:00
parent e9f4352640
commit fa2835ebcc
+18 -1
View File
@@ -32,7 +32,8 @@ A project is always a Rust program built on the engine.
ger40-lab/ # your research project — a separate Rust crate (cdylib)
├── Aura.toml # STATIC context only: data paths, instrument/pip
│ # metadata, default broker & window, runs dir (no logic)
├── Cargo.toml # cdylib; depends on aura-core/aura-std (+ shared node crates)
├── Cargo.toml # cdylib; depends on aura-core/aura-std (+ shared node crates);
│ # carries an empty [workspace] table (see note below)
├── CLAUDE.md # the project's own skills wiring (authoring discipline)
├── .claude/dev-cycle-profile.yml
├── nodes/ # project-local node & strategy blueprints (Rust)
@@ -42,6 +43,22 @@ ger40-lab/ # your research project — a separate Rust crate (cd
└── (frozen bots, …)
```
> **The empty `[workspace]` table.** A project crate is its own cargo workspace,
> never a member of the engine's. This matters the moment a project lives *under*
> the engine repo (common while authoring, before it moves to its own repo):
> cargo otherwise walks up, finds the engine's root manifest, and refuses to
> build —
>
> ```
> error: current package believes it's in a workspace when it's not:
> ... to keep it out of the workspace, add an empty [workspace] table ...
> ```
>
> The fix is cargo's own hint: an empty `[workspace]` table in the project's
> `Cargo.toml`. It pins the crate as a standalone workspace root and costs
> nothing when the project later sits in its own repo. The future `aura new`
> scaffolder will emit this line; until then, add it by hand.
## Where reusable nodes live (three tiers)
Everything that plugs into the engine is fractally a `Node`. Reuse is plain