docs(scaffold): add a Logos Scaffold section for the module

[weboko]

Draft. First cut of a docs package for logos-scaffold, focused on the module development loop against Basecamp.

What this adds

A new docs/scaffold/ section with three pages:

Page	Type	Covers
About Logos Scaffold	concept	What scaffold manages (LEZ projects and Basecamp modules), project layout, profiles, and the boundary against logos-module-builder.
Develop a Logos module with Logos Scaffold	procedure	Install, lgs init, basecamp setup / modules / install / launch, the iteration loop, two-instance testing, and build-portable.
Troubleshoot Logos module development with Basecamp	troubleshooting	Symptom-to-fix coverage for failures that build cleanly and misbehave at runtime.

The five field notes this PR was opened to capture:

1. The dev loop. nix build .#lgx does not update a running Basecamp. Documented as three moves — rebuild, reinstall into every base directory, restart — plus the fact that lgs basecamp launch <profile> collapses all three, and that relaunching one profile leaves the other on the old build.
2. Two instances on one machine. --user-dir / LOGOS_USER_DIR and scaffold profiles, with a table of how the base directory resolves, including the Dev suffix that non-portable builds append to the application data location.
3. macOS socket path budget. The 104-byte sun_path cap, the Unix socket path too long error, and keeping XDG_RUNTIME_DIR / TMPDIR short (/tmp/lgs-<profile>).
4. QML qmldir naming. Why a bare import "." lets same-basename types cross-match between modules in one host process, and the named-module layout that avoids it.
5. Nix and git tracking. Flakes with src = ./. only see git-tracked files, so a new qmldir or config file must be staged before the build or it is silently omitted.

Additional material drawn from the scaffold and module-builder repositories: follows wiring for transitive logos-module-builder inputs, unresolved dependency errors from basecamp modules, sibling sub-flake override limits, doctor drift, the ui-dev QML hot-reload loop, absolute LOGOS_DATA_DIR on the macOS bundle, and how to collect diagnostics with lgs report.

Wiring

• New scaffoldSidebar in sidebars.ts, added to the Explore dropdown in docusaurus.config.ts.
• Both new task pages linked from the Build an app journey under Build modules.
• docs/get-started/logos-ecosystem-repositories.md now points at logos-co/logos-scaffold (the logos-co/scaffold URL redirects to it) with a description matching what the tool actually does.

Verification

• npm run build passes with no broken links or anchors (onBrokenLinks: 'throw').
• British spelling checked against .github/styles/Logos/BritishSpelling.yml.
• Commands, paths, env vars, and error strings were taken from logos-scaffold (src/commands/basecamp.rs, src/constants.rs, docs/basecamp-module-requirements.md), logos-basecamp (app/utils/LogosBasecampPaths.h, README.md), and logos-module-builder (lib/mkLogosQmlModule.nix, README.md).

Open questions for review

• authors: is empty in the three new files — please fill in the handles that should be credited.
• product: core was chosen for the frontmatter since the taxonomy in CONTRIBUTING.md has no scaffold area. Happy to change it.
• doc_type: troubleshooting is sanctioned by CONTRIBUTING.md but is the first use of that type in docs/. There is no template committed under resources/templates/ yet, so the structure is symptom / cause / fix with an index table at the top.
• The QML cross-matching explanation is the part most worth an SME check.

[weboko]

triggering AI review now, let's see

[weboko]

Dogfooded this on a clean Ubuntu 24.04 container, following the module guide end to end: installed Nix (flakes), cloned logos-co/scaffold @ 7c2578d — the exact rev the last commit says it refreshed against — cargo install --path ., then lgs init, lgs doctor, lgs basecamp docs, lgs basecamp setup (full Nix build of Basecamp + lgpm, ~8 min), lgs basecamp paths, and lgs basecamp doctor. Also ran yarn build on this branch.

This holds up unusually well. I went looking for drift and mostly found the docs matching the source line for line. Things I checked and confirmed:

• Every documented subcommand and flag exists: --show, --print-output, --log-file[=PATH], --json, --variant, --module, completions bash|zsh, and all of run's flags (--profile, --reset/--no-reset, --post-deploy, --no-post-deploy, --watch).
• init's .gitignore append and the scaffold.toml.bak migration, both exactly as described.
• setup printed seeded profiles: alice, bob, and neither basecamp nor lgpm landed on PATH — as line 78 says.
• The launch env table: launch_env sets the three XDG vars under the profile dir plus LOGOS_PROFILE, and BASECAMP_MODULE_ROOT_ENV_VARS really is ["LOGOS_DATA_DIR", "LOGOS_USER_DIR"] — line 283's "sets both" is right. The portable attrs bin-macos-app / bin-appimage / bin-bundle-dir match constants.rs too.
• The runtime_dir resolution order (config → /tmp/lgs-<profile> on macOS → in-profile xdg-tmp) matches resolve_profile_runtime_dir exactly, and paths alice --json returned xdg_runtime_dir: null with tmpdir pointing at xdg-tmp on Linux, which is precisely what the table predicts.
• The Dev suffix field note (line 272-278) showed up live: modules_dir resolved to .../xdg-data/Logos/LogosBasecamp**Dev**/modules.
• The QML claim about logos-module-builder generating module com.logos.module.<name> and preserving an author-supplied qmldir — verified in lib/mkLogosQmlModule.nix:127-143.
• The subtle one on the LEZ page: profiles shadow rather than inherit [run]. config.rs parses each profile key with .unwrap_or(true/false), so a key the profile omits falls back to its own default, not your inline value. The warning is correct.
• yarn build passes clean with onBrokenLinks: 'throw', no warnings, and every in-page anchor I extracted resolves to a real heading.

Three fixes inline, all small — a factual overreach on the about page, an undocumented init side effect that writes un-gitignored files into the repo, and an off-by-one in a data-loss warning.

What I could not exercise: the GUI half. This container is headless (DISPLAY unset), and the page correctly lists a graphical environment as a prerequisite, so Step 4's launch, Step 6's two-instance peer-to-peer test, and every runtime symptom in the troubleshooting page (socket path overflow, QML cross-matching, instance collision, blank macOS UI) are unverified here. I got as far as setup completing and the profile paths resolving. Those runtime sections read as plausible and internally consistent, and the mechanisms behind them check out in source — the logos_token_<module> socket collision is described in a comment in launch_env almost verbatim — but someone should confirm the observed symptoms on a desktop before this leaves draft.

One thing in the PR description rather than the docs: it says the ecosystem-repositories change "now points at logos-co/logos-scaffold (the logos-co/scaffold URL redirects to it)". Both halves are backwards — the diff points at logos-co/scaffold, and it's logos-co/logos-scaffold that 301s to it. The docs get this right (about page line 22 states the direction correctly); only the description needs a touch-up.

[weboko]

"Every command refuses to run outside such a project" isn't quite right, and it contradicts the procedure page.

Verified against logos-scaffold 0.1.1 built from logos-co/scaffold @ 7c2578d, running from an empty directory with no scaffold.toml:

lgs basecamp docs    -> # Basecamp Module Requirements     (works)
lgs init             -> scaffold.toml created at ...       (works)
lgs --version        -> logos-scaffold 0.1.1               (works)
lgs doctor           -> error: This command must be run inside a logos-scaffold project.

create / new are in the same category as init — they exist precisely to be run outside a project. And basecamp docs working outside is a deliberate feature that develop-a-logos-module-with-logos-scaffold.md:101 calls out explicitly: "It works outside a scaffold project too, so you can read the contract before running lgs init." As written, this page contradicts that.

Suggested change

	Scaffold works on a project directory that contains a `scaffold.toml` file at its root. Every command refuses to run outside such a project, and `lgs init` creates the file for an existing project.
	Scaffold works on a project directory that contains a `scaffold.toml` file at its root. Project-scoped commands refuse to run outside such a project; the exceptions are `create` and `new`, which bootstrap one, `lgs init`, which creates the file for an existing project, and `lgs basecamp docs`, which prints the module contract from anywhere.

[weboko]

init has three more side effects worth documenting, because they land in the user's repo and are not covered by the .scaffold gitignore entry.

Running lgs init in a fresh git repo (scaffold @ 7c2578d):

$ lgs init
scaffold.toml created at /.../scaffold.toml. Run 'lgs setup' to clone LEZ and build dependencies.
AI skills installed under .claude/skills/, .cursor/rules/, and AGENTS.md.

$ ls -a
.claude  .cursor  .git  .gitignore  .scaffold  AGENTS.md  scaffold.toml

So beyond the three things this paragraph lists, init also writes .claude/skills/, .cursor/rules/, and a top-level AGENTS.md. Only .scaffold gets appended to .gitignore, so on the next git add -A all three get committed — which matters given the page later tells readers to run exactly that (line 218, the git-tracking warning).

Re-running init refreshes them rather than leaving them alone (AI skills refreshed under .claude/skills/, .cursor/rules/, AGENTS.md.), so a project that deletes them gets them back on the next init.

Both other claims in this paragraph check out exactly: I confirmed the .gitignore append, and the migration path writes scaffold.toml.bak and prints the schema diff.

Suggested change

`init` writes `scaffold.toml`, creates `.scaffold/`, and appends `.scaffold` to `.gitignore`. Run it once per project. If the project already has a `scaffold.toml` from an older schema, `init` migrates it in place and leaves a `scaffold.toml.bak` next to it.

`init` writes `scaffold.toml`, creates `.scaffold/`, and appends `.scaffold` to `.gitignore`. It also installs AI-assistant scaffolding into the project — `.claude/skills/`, `.cursor/rules/`, and a top-level `AGENTS.md` — which are **not** gitignored, so decide whether to commit or ignore them before your next `git add -A`. Run it once per project; re-running refreshes the assistant files. If the project already has a `scaffold.toml` from an older schema, `init` migrates it in place and leaves a `scaffold.toml.bak` next to it.

[weboko]

Off-by-one, and the numbering collides with the page's own ## Step N headings.

Line 130 lists launch's four moves in order: (1) kills leftover processes, (2) removes the profile's state, (3) replays the install, (4) starts Basecamp. The scrub is the second, not the third — the third is the reinstall. I confirmed the real order in src/commands/basecamp.rs, which runs kill_process_tree → seed_profiles → scrub_profile_data_and_cache → seed_profiles → install_sources_into_profiles → launch.

"step 3" also reads as a pointer to this page's ## Step 3: Build and install the module, which contains no scrub at all — so naming the move is clearer than numbering it:

Suggested change

	The scrub in step 3 is deliberate: every launch starts from a clean profile, so identity keys, conversations, and any other in-app state are discarded. That is what makes runs reproducible. If you need state that survives a restart, run Basecamp yourself against a fixed base directory as described in [Step 6](#step-6-run-two-instances-side-by-side).
	The state removal above is deliberate: every launch starts from a clean profile, so identity keys, conversations, and any other in-app state are discarded. That is what makes runs reproducible. If you need state that survives a restart, run Basecamp yourself against a fixed base directory as described in [Step 6](#step-6-run-two-instances-side-by-side).