Documents
Organizing Content
Workspaces, projects, and folders — a flexible hierarchy that scales from a single team to an entire organization.
The Content Hierarchy
Every piece of content in Stable Baseline lives within a four-level hierarchy. Each level serves a distinct organizational purpose:
Workspace
Top-level boundary
A workspace is your highest-level organizational boundary. Think of it like a team or a department. Each workspace has its own members, permissions, and billing. Most organizations use one workspace per team or business unit.
Project
A collection of related docs
A project groups related documents together. It could represent a product, a service, a client engagement, or any logical body of work. Projects contain folders and documents, and each project has its own permissions that roll up from the workspace.
Folder
Nestable grouping
Folders organize documents within a project. They can be nested — folders inside folders — giving you as much or as little depth as you need. Folder structure is completely flexible: group by feature, by lifecycle stage, by audience, or however makes sense for your team.
Document
The actual content
The document is your unit of content — a rich CDMD file with text, diagrams, images, and version history. Documents live inside folders (or directly at the project root). Each document has its own title, version timeline, and can be independently shared or linked.
Folder Nesting
Folders support unlimited nesting depth. This lets you mirror your actual project structure:
📂 Auth Service ├── 📂 Architecture │ ├── 📄 System Context (C4) │ ├── 📄 Container Diagram │ └── 📄 Data Flow ├── 📂 API Reference │ ├── 📄 /auth/login │ ├── 📄 /auth/refresh │ └── 📄 /auth/revoke ├── 📂 Runbooks │ ├── 📂 Incident Response │ │ ├── 📄 Token Leak Playbook │ │ └── 📄 Rate Limiting Escalation │ └── 📄 Deployment Checklist └── 📄 README
Nest as deep as makes sense for your content. There is no hard limit. However, as a best practice, keep nesting to 3–4 levels to maintain discoverability.
When to Use What
| Level | Use When… | Examples |
|---|---|---|
| Workspace | You need a completely separate access boundary (different team, different client, different billing). | Eng team, Platform ops, Client XYZ |
| Project | You have a logical body of work with its own docs — a service, a product, an engagement. | Payment Service, iOS App, SOC 2 Audit |
| Folder | You want to group documents by topic, area, or stage within a project. | Architecture, API Specs, Decision Logs |
| Document | You have a single piece of content — a design doc, a runbook, a spec. | System Context Diagram, Deploy Guide |
Organizational Patterns
Here are some patterns that work well for teams of different sizes:
Small Team (1 workspace, few projects)
One workspace for the whole team. One project per product or service. Use folders to separate architecture docs, API specs, and guides. Simple and flat.
Engineering Org (1 workspace, many projects)
One workspace for engineering. A project for each microservice or component. Consistent folder structure within each project (Architecture, API, Runbooks, Decision Logs). Makes it easy for anyone to navigate to the right place in any service.
Multi-Team Org (multiple workspaces)
Separate workspaces for engineering, product, and ops. Each team manages their own content and permissions. Use MCP API keys scoped to specific workspaces for cross-team integrations.
Consulting / Agency (workspace per client)
One workspace per client for clean access separation. Projects within each workspace for different engagements or deliverables. Strict permission boundaries ensure no cross-client data leaks.
Tips
- • Use project-level navigation (
getProjectHierarchy) to see the full tree in one call. - • Keep folder names short and descriptive — they appear in sidebar navigation and breadcrumbs.
- • Documents at the project root are fine for READMEs and high-level overviews.
- • Use consistent folder names across projects (e.g. always "Architecture", "API", "Runbooks") so people know where to look.