From fa2835ebccaaeb1ed23e62fb44fc498c6b63bf03 Mon Sep 17 00:00:00 2001 From: Brummel Date: Thu, 4 Jun 2026 17:47:45 +0200 Subject: [PATCH] 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 --- docs/project-layout.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/project-layout.md b/docs/project-layout.md index 528a23e..8f25a79 100644 --- a/docs/project-layout.md +++ b/docs/project-layout.md @@ -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