Ecosystem desk
Work across kernel, studio, cloud, and docs from one Trellis workspace with repo aliases and symlink-safe graphs.
Ecosystem desk
The TRELLIS workspace is a local desk: orchestration scripts, naming docs, and symlinks to the product repos. It is not a monorepo. Each spoke (kernel/, studio/, cloud/, docs/) keeps its own .trellis graph.
~/TURTLE/Projects/TRELLIS/
├── justfile, ONTOLOGY.md, graph/ecosystem.json
├── kernel/ → trellis (platform)
├── studio/ → turtlecode (IDE)
├── cloud/ → trellis-cloud
└── docs/ → trellis.computer site
Open this folder in your editor when you want one window for the whole stack.
Trellis CLI by repo alias
From the desk root, just trellis resolves aliases from graph/ecosystem.json and forwards -p with a canonical path (symlink-safe):
cd ~/TURTLE/Projects/TRELLIS
just trellis repos
just trellis -r studio issue list
just trellis -r kernel status
just trellis -r docs status
Same graph whether you use TRELLIS/studio or the real clone path under Packages/.
Without the wrapper
trellis issue list -p studio
cd studio && trellis issue list
Most commands accept -p, --path. Trellis walks up to the nearest .trellis root.
Which graph for which work
| Work | Graph | Command |
|---|---|---|
| Studio product (WU, sessions, app) | studio/ | just trellis -r studio … |
| Kernel / CLI / engine | kernel/ | just trellis -r kernel … |
| Public docs site | docs/ | just trellis -r docs … |
| Release train, hooks, desk tooling | desk (optional) | just trellis -r desk … after trellis init at desk root |
Do not merge spoke graphs into one store. Link across repos in issue descriptions or with multi-repo refs when you need traceability.
Studio and symlink paths
Trellis Studio keys its backend engine by canonical directory. Opening a project via a symlinked spoke path (TRELLIS/studio) sees the same work units and .trellis/ data as the real clone path.
The file browser resolves symlinked folders to directories or files in the tree. Listing the desk root (TRELLIS/) shows desk files and symlink spokes; it does not walk into spoke clones (that keeps the explorer and Go to file fast). To edit or search inside turtlecode, open studio/ (or the real clone) as the Studio project.
Go to file at the desk root indexes the desk tree only. Symlink spokes such as studio/ and kernel/ appear as entries; open the spoke directory as the workspace to fuzzy-search files inside that repo. Local .trellis/ graphs stay out of the Studio file index.
For VS Code or Cursor search at the desk root, use search.followSymlinks and exclude .trellis (the desk .vscode/settings.json sets search.exclude for **/.trellis). Ripgrep-style search in the desk uses .ignore to un-ignore symlinked spokes while git still ignores them.
Agent hooks and docs drift
Desk hooks share scripts under .cursor/hooks/ and queue docs drift when you edit kernel/, studio/, or cloud/. Inspect with:
just docs-check
When drift is pending, follow .windsurf/workflows/sync-docs.md (or ask your agent to "sync docs"), update pages under docs/content/ per tooling/docs-sync/manifest.json, then clear the queue:
just docs-check --clear
Commit doc changes in the docs/ repo separately from product repos.
Publishing turtlecode (npm)
Prefer the release train (just release --execute --yes) so turtlecode and platform backend packages publish through GitHub Actions (publish-turtlecode.yml). For a local fallback from the desk:
# desk root — loads NPM_TOKEN from .env, bumps patch, builds all platforms, publishes
just publish-studio patch
# resume after a partial failure (no version bump, no rebuild)
cd studio && just publish-resume
Put an npm Automation token in desk .env as NPM_TOKEN (or NODE_AUTH_TOKEN). The desk and studio recipes source that file automatically; packages/cli/script/publish.ts also reads desk .env when you invoke the script directly. With a valid automation token you skip the Continue? prompt and npm OTP prompts during the multi-package publish (main turtlecode plus turtlecode-backend-* targets).
| Flag / env | Effect |
|---|---|
NPM_TOKEN in desk .env | Non-interactive auth; skips Continue when set |
--yes / -y | Skip Continue without a token |
--dry-run | Bump preview only; npm publish --dry-run for each package |
--no-build | Publish existing platforms/ artifacts (just publish-resume) |
--otp <code> / NPM_OTP | One-time password when not using an automation token |
Granular publish tokens may still require --otp per run. See tooling/RELEASING.md for the full train, pin sync (just sync-pins), and kernel publish (just publish-kernel).
| Agent | Hooks config | Instructions |
|---|---|---|
| Cursor | .cursor/hooks.json | .cursor/rules/, AGENTS.md |
| Windsurf Cascade | .windsurf/hooks.json | .windsurf/workflows/ |
| Codex | .codex/hooks.json | AGENTS.md, .codex/skills/trellis-desk/ |
| Copilot CLI | .github/hooks/trellis-desk.json | .github/copilot-instructions.md |
| Gemini CLI / Antigravity | .gemini/settings.json | .gemini/GEMINI.md |
OpenCode skills and commands live in studio/.opencode/ (product graph, not desk shell).
Trellis Studio's agentic IDE experience is powered by opencode, the open-source agentic coding framework.
Environment
export TRELLIS_REPO=studio # default repo for `just trellis` without -r
export TRELLIS_BIN=trellis # override CLI binary
See also Trellis Studio introduction and the CLI reference.