1---
2name: spaces
3description: create and manage spaces, configure access control, set up custom domains, and understand the identity model
4---
5
6# spaces
7
8a space is the top-level container in sublimated. every space has a unique slug, an owner, and contains items (files and folders) organized as an ltree hierarchy.
9
10## creating a space
11
12```
13POST https://api.sublimated.com/v1/spaces
14{ "slug": "my-project" }
15```
16
17or via git — pushing to a new slug auto-creates the space.
18
19## space types
20
21- `personal` — default, owned by a user
22- `org` — organization space (shared ownership)
23
24## visibility
25
26- `private` — only authenticated users with access rules can read
27- `public` — anyone can clone/read, writes still require auth
28
29set via API or `.sublimated/access.yml`.
30
31## access control
32
33access is configured per-space via `.sublimated/access.yml`, pushed through git:
34
35```yaml
36rules:
37  - identifier: alice
38    role: editor
39  - identifier: "*@company.com"
40    role: viewer
41  - identifier: "*"
42    role: viewer
43    paths: ["docs"]
44```
45
46roles (highest to lowest privilege): owner, admin, editor, commenter, viewer.
47
48rules support:
49- username: `alice`
50- email: `bob@example.com`
51- domain wildcard: `*@company.com`
52- public wildcard: `*` (anonymous access)
53- path scoping: restrict access to specific folders
54
55access config is parsed, merged hierarchically (deeper folders override parents), and cached in KV for fast lookups.
56
57## scoped tokens
58
59create tokens with restricted permissions:
60
61```
62POST https://api.sublimated.com/v1/spaces/{slug}/tokens
63{
64  "label": "CI deploy",
65  "permissions": ["read", "write"],
66  "pathScope": ["src"],
67  "branchPatterns": ["refs/heads/main"],
68  "expiresIn": "30d"
69}
70```
71
72token prefix: `sk_`. use as Bearer token or git password.
73
74## identity model (progressive trust)
75
76- level 0: anonymous — auto-created on first interaction, gets personal space + scoped token
77- level 1: email verified
78- level 2: identity linked (GitHub, etc.)
79- level 3: full account
80- level 4: system only (internal service account)
81
82anonymous users can push to their own space immediately — no signup friction.
83
84## item hierarchy
85
86items are organized as ltree paths: `slug.folder.subfolder.file-md`
87
88- every folder is independently clonable as a git repo
89- items track: name, type, path, contentHash, sizeBytes, currentVersion
90- folders are implicit from paths but also stored as items (for metadata, permissions)
91
92## quotas
93
94spaces can have limits:
95- `maxStorageBytes` — storage cap
96- `maxRequestsPerDay` — API rate limit
97
98when usage exceeds 80%, a persistent warning appears on every response. at 95%+, severity escalates to error.
99
100## space configuration
101
102`.sublimated/config.yml` in the space root configures:
103- build settings (which branches trigger Docker builds)
104- custom domain mappings
105- default visibility
106- feature flags
107
108pushed via git, parsed on push, takes effect immediately.
109
110## see also
111
112- git-workflow — clone and push to spaces
113- data-api — API endpoints for space management
114- connectors — sync external data into a space

1# file-attributes
2
3read sublimated metadata directly from local files via macOS extended attributes. no API calls needed — version, author, commit hash, and AI attribution are available on every synced file.
4
5## reading xattrs
6
7every file synced via sublimated's FileProvider carries metadata as extended attributes. read them with `xattr -p`:
8
9```bash
10# web URL for the file
11xattr -p "com.sublimated.url#PS" README.md
12# → sublimated.com/anton/blog/readme_md
13
14# item ID (stable across renames/moves)
15xattr -p "com.sublimated.id#PS" README.md
16# → itm_01JQXYZ...
17
18# current version number
19xattr -p "com.sublimated.version#PS" README.md
20# → 42
21
22# BLAKE3 content hash
23xattr -p "com.sublimated.content-hash#PS" README.md
24# → blake3-a1b2c3d4...
25
26# who created this file
27xattr -p "com.sublimated.created-by#PS" README.md
28# → Alice
29
30# who last modified this file
31xattr -p "com.sublimated.modified-by#PS" README.md
32# → Bob
33
34# what kind of actor last modified it
35xattr -p "com.sublimated.modified-by-type#PS" README.md
36# → person
37
38# last commit hash
39xattr -p "com.sublimated.commit#PS" README.md
40# → abc123def456
41```
42
43## xattr reference
44
45| xattr key (with flag suffix) | value | notes |
46|---|---|---|
47| `com.sublimated.url#PS` | web link | `sublimated.com/{space}/{path}` |
48| `com.sublimated.id#PS` | item ID | stable across renames |
49| `com.sublimated.version#PS` | version number | integer, increments on each edit |
50| `com.sublimated.content-hash#PS` | BLAKE3 hash | files only, nil for folders |
51| `com.sublimated.created-by#PS` | author name | who created the file |
52| `com.sublimated.modified-by#PS` | author name | who last edited the file |
53| `com.sublimated.modified-by-type#PS` | actor type | `person`, `ai_agent`, or `bot` |
54| `com.sublimated.commit#PS` | commit hash | last commit that touched this file |
55
56## modified-by-type values
57
58- `person` — human user editing via Finder, CLI, or web
59- `ai_agent` — AI assistant (Claude, GPT, etc) editing via API or MCP
60- `bot` — automated system (CI, sync, transform)
61
62use this to determine if a file was last touched by a human or AI. useful for:
63- audit trails ("who wrote this code?")
64- trust scoring ("is this AI-generated?")
65- workflow routing ("send human-written files to review, auto-approve bot changes")
66
67## reading from filesystem (Finder → server)
68
69sublimated reads two macOS metadata attributes from synced files and stores them server-side:
70
71| filesystem xattr | server key | table | notes |
72|---|---|---|---|
73| `com.apple.metadata:kMDItemFinderComment` | `finder_comment` | item_text_attrs | Finder "Get Info" comment |
74| `com.apple.metadata:kMDItemKeywords` | `spotlight_keywords` | item_json_attrs | Spotlight keywords array |
75
76set a Finder comment via Get Info (Cmd+I) or:
77```bash
78xattr -w com.apple.metadata:kMDItemFinderComment "$(python3 -c "import plistlib; import sys; sys.stdout.buffer.write(plistlib.dumps('my comment'))")" README.md
79```
80
81## platform notes
82
83- xattrs are macOS-only (FileProvider). on Linux/Windows, same data is accessible via the API and git
84- the `#PS` suffix is added by `xattr_name_with_flags()` — it means SYNCABLE + NO_EXPORT
85- folders get all xattrs except `content-hash` (folders have no content hash)
86- xattrs are set by the FileProvider extension, not by scripts — they appear automatically on synced files

1---
2name: cdn
3description: serve content from the edge — content-addressed URLs, format negotiation, shadow branch rendering, and caching
4---
5
6# cdn
7
8sublimated serves content through a global CDN backed by content-addressed storage (CAS). every blob is immutable and cached aggressively at the edge.
9
10## content-addressed storage
11
12all content is stored by its BLAKE3 hash. same bytes = same hash = same URL forever. no cache invalidation needed — new content gets a new hash.
13
14upload content:
15```
16PUT https://api.sublimated.com/v1/spaces/{slug}/content
17Content-Type: application/octet-stream
18
19{raw bytes}
20```
21
22returns: `{ contentHash: "blake3-af13...", sha256Hash: "...", sizeBytes: 1234 }`
23
24download by hash:
25```
26GET https://api.sublimated.com/v1/spaces/{slug}/content/{hash}
27```
28
29check existence:
30```
31POST https://api.sublimated.com/v1/cas/check
32{ "hashes": ["blake3-af13...", "blake3-bc24..."] }
33```
34
35returns: `{ "have": [...], "missing": [...] }`
36
37## URL routing and format negotiation
38
39content is served at `sublimated.com/{space}/{path}` with format selection:
40
41explicit extension:
42- `/space/path/file.md` — raw markdown (CAS blob)
43- `/space/path/file.html` — rendered HTML (from shadow branch)
44- `/space/path/file.json` — AST JSON (from shadow branch parser)
45
46content negotiation (extensionless URLs):
47- `Accept: text/html` → rendered HTML
48- `Accept: text/markdown` → raw markdown
49- `Accept: application/json` → AST JSON
50- no Accept header → HTML (default)
51
52folder vs file conflict (`hello.md` + `hello/`):
53- `/hello` → the file (rendered as HTML)
54- `/hello/` (trailing slash) → folder index
55
56## shadow branch rendering
57
58the CDN resolves formats from shadow branches, computed automatically on push:
59
60- raw content → CAS blob via item's `contentHash`
61- rendered HTML → `refs/sbl/{branch}/html/{path}`
62- AST JSON → `refs/sbl/{branch}/markdown/{path}.ast.json`
63- metadata → `refs/sbl/{branch}/meta/{path}.json`
64
65shadow data is incremental — only changed items are reprocessed on push.
66
67## caching
68
69CAS blobs are cached at the edge using Cloudflare Cache API:
70- cache key = content hash (immutable, never invalidated)
71- TTL: 24h+ (content never changes, TTL only controls eviction)
72- per-colo caching: fills naturally as users access content from each location
73
74what is cached:
75- CAS blobs (API downloads and git clone)
76- materialized files (keyed by `materializedHash`)
77- git pack responses (keyed by ref + commit hash)
78
79what is NOT cached:
80- mutable data (item listings, space metadata, refs)
81- user-specific data (access rules, sessions, tokens)
82
83## large file uploads
84
85for files over 100MB, use presigned R2 upload:
86
87```
88POST https://api.sublimated.com/v1/spaces/{slug}/cas/presign
89```
90
91returns a presigned URL for direct R2 upload.
92
93## CDN URLs in feedback
94
95every write operation includes CDN URLs in the response:
96
97API response: `_meta.links.cdn: ["https://sublimated.com/space/path/file"]`
98
99git push: sideband line with view URL
100
101## see also
102
103- shadow-branches — how derived data is stored as orphan git refs
104- data-api — content upload and download endpoints
105- transforms — shadow branches that power format rendering
106- git-workflow — how pushes trigger CDN content updates

1{
2  "version": "1.0",
3  "name": "sublimated",
4  "description": "agent skills for the sublimated platform",
5  "base_url": "https://sublimated.com/.well-known/skills",
6  "skills": [
7    {
8      "name": "identity",
9      "description": "onboard as an agent or user — create an identity, get a token, and start working with zero friction"
10    },
11    {
12      "name": "spaces",
13      "description": "create and manage spaces, configure access control, set up custom domains, and understand the identity model"
14    },
15    {
16      "name": "configuration",
17      "description": "configure spaces, access control, actions, schemas, and encryption — all versioned in git via .sublimated/ folder"
18    },
19    {
20      "name": "actions",
21      "description": "built-in transforms, validators, and effects — the @sublimated/* action catalog and how to define custom actions"
22    },
23    {
24      "name": "git-workflow",
25      "description": "clone, push, and fetch spaces using git — read sideband feedback, discover shadow refs and capabilities"
26    },
27    {
28      "name": "transforms",
29      "description": "understand reactive transforms, shadow branches, effects, and how pushes trigger automated workflows"
30    },
31    {
32      "name": "cdn",
33      "description": "serve content from the edge — content-addressed URLs, format negotiation, shadow branch rendering, and caching"
34    },
35    {
36      "name": "runs",
37      "description": "inspect CI runs, builds, deploys, and transforms — fetch the runs shadow branch and read runs.jsonl"
38    },
39    {
40      "name": "usage",
41      "description": "inspect metered usage — commit stats, compute duration, and other usage events via the usage shadow branch"
42    },
43    {
44      "name": "shadow-branches",
45      "description": "understand shadow branches — derived data stored as orphan git refs alongside your content branches"
46    },
47    {
48      "name": "sessions",
49      "description": "track coding sessions — auto-created on git push, upload transcripts for full conversation replay and analysis"
50    },
51    {
52      "name": "file-attributes",
53      "description": "read sublimated metadata from local files via extended attributes — version, author, commit hash, AI attribution"
54    }
55  ]
56}