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