sfora-cli 0.8.0 → 0.10.0

package/README.md

@@ -21,7 +21,9 @@ shell interpreter backs the interactive mode).
 ├── projects/<slug>/posts/<YYYY-MM-DD-title>.md     # published posts  (GET·PUT·DELETE)
 │                  /drafts/<…>.md                   # your drafts      (GET·PUT·DELETE)
 │                  /board/<NN-col>/<NNNN-card>.md   # tasks by column  (GET·PUT·DELETE)
-│                  /docs/<…>.md                     # docs / notes     (GET·PUT·DELETE)
+│                  /library/documents/<…>.md        # docs / notes     (GET·PUT·DELETE)
+│                          /files/<…>                # uploaded files  (GET)
+│                          /repositories/<repo>/…    # source trees     (GET)
 ├── inbox/mentions.md                               # unread mentions  (GET)
 └── me/api-key                                      # your identity    (GET)
 ```
@@ -154,11 +156,11 @@ sfora:/$ cd /projects/general/posts        # cwd persists across commands
 sfora:/projects/general/posts$ exit
 ```
 
-Writing a file `PUT`s it (creating a post or, within the 5-minute edit window,
-updating one you authored). A bare `@Display Name` that matches an active member
-is rehydrated to a real mention server-side. `rm` soft-deletes (author or org
-admin/owner). Drafts live under `…/drafts/`; a `scheduledFor:` in the frontmatter
-schedules auto-publish.
+Writing a post file publishes a new immutable record. Edit mutable work under
+`…/drafts/` and publish only when it is ready; overwriting an existing published
+filename is rejected. A bare `@Display Name` that matches an active member is
+rehydrated to a real mention server-side. `rm` soft-deletes (author or org
+admin/owner). A `scheduledFor:` in draft frontmatter schedules auto-publish.
 
 ## MCP server (Claude Desktop / Cursor)
 

package/dist/SforaFs.js

@@ -79,6 +79,15 @@ function classify(path) {
         if (dir === "links.md" && seg.length === 3) {
             return { kind: "linksFile", slug };
         }
+        if (dir === "plan.md" && seg.length === 3) {
+            return { kind: "planFile", slug };
+        }
+        if (dir === "map.md" && seg.length === 3) {
+            return { kind: "mapFile", slug };
+        }
+        if (dir === "asks.md" && seg.length === 3) {
+            return { kind: "asksFile", slug };
+        }
         if (dir === "posts" || dir === "drafts") {
             if (seg.length === 3)
                 return { kind: "postsDir", slug, dir };
@@ -92,6 +101,38 @@ function classify(path) {
             if (seg.length === 4)
                 return { kind: "docFile", slug, filename: seg[3] };
         }
+        if (dir === "artifacts") {
+            if (seg.length === 3)
+                return { kind: "filesDir", slug };
+            if (seg.length === 4)
+                return { kind: "artifactFile", slug, filename: seg[3] };
+        }
+        if (dir === "library") {
+            if (seg.length === 3)
+                return { kind: "libraryDir", slug };
+            if (seg[3] === "documents") {
+                if (seg.length === 4)
+                    return { kind: "docsDir", slug };
+                if (seg.length === 5)
+                    return { kind: "docFile", slug, filename: seg[4] };
+            }
+            if (seg[3] === "files") {
+                if (seg.length === 4)
+                    return { kind: "filesDir", slug };
+                if (seg.length === 5)
+                    return { kind: "artifactFile", slug, filename: seg[4] };
+            }
+            if (seg[3] === "repositories") {
+                if (seg.length === 4)
+                    return { kind: "repositoriesDir", slug };
+                return {
+                    kind: "repositoryPath",
+                    slug,
+                    repository: seg[4],
+                    path: seg.slice(5).join("/"),
+                };
+            }
+        }
         if (dir === "pulls") {
             if (seg.length === 3)
                 return { kind: "pullsDir", slug };
@@ -212,9 +253,45 @@ export class SforaFs {
         return this.#cached(key, async () => {
             const notes = await this.#client.listNotes(slug);
             this.#entrySnapshots.set(`/projects/${slug}/docs`, notes.map((n) => n.filename));
+            this.#entrySnapshots.set(`/projects/${slug}/library/documents`, notes.map((n) => n.filename));
             return notes;
         });
     }
+    #invalidateNotes(slug) {
+        this.#cache.delete(`docs:${slug}`);
+    }
+    #listArtifacts(slug) {
+        return this.#cached(`artifacts:${slug}`, async () => {
+            const artifacts = await this.#client.listArtifacts(slug);
+            const names = artifacts.map((artifact) => artifact.name);
+            this.#entrySnapshots.set(`/projects/${slug}/artifacts`, names);
+            this.#entrySnapshots.set(`/projects/${slug}/library/files`, names);
+            return artifacts;
+        });
+    }
+    #listRepositories(slug) {
+        return this.#cached(`repositories:${slug}`, async () => {
+            const repositories = await this.#client.listRepositories(slug);
+            this.#entrySnapshots.set(`/projects/${slug}/library/repositories`, repositories.map((repository) => repository.dirname));
+            return repositories;
+        });
+    }
+    #repositoryTree(slug, repository) {
+        return this.#cached(`repository-tree:${slug}/${repository}`, async () => {
+            const tree = await this.#client.getRepositoryTree(slug, repository);
+            this.#entrySnapshots.set(`/projects/${slug}/library/repositories/${repository}`, tree.entries.map((entry) => entry.path));
+            return tree;
+        });
+    }
+    async #repositoryEntry(slug, repository, path) {
+        if (!path) {
+            const repositories = await this.#listRepositories(slug);
+            return repositories.some((candidate) => candidate.dirname === repository)
+                ? { kind: "directory" }
+                : undefined;
+        }
+        return (await this.#repositoryTree(slug, repository)).entries.find((entry) => entry.path === path);
+    }
     // ─── pull requests cache (read-only) ─────────────────────────────
     #listPulls(slug) {
         const key = `pulls:${slug}`;
@@ -381,6 +458,31 @@ export class SforaFs {
                 catch (e) {
                     throw fromApi(e, "open", normalize(path));
                 }
+            case "artifactFile":
+                try {
+                    return await this.#client.readArtifact(loc.slug, loc.filename);
+                }
+                catch (e) {
+                    throw fromApi(e, "open", normalize(path));
+                }
+            case "repositoryPath": {
+                if (!loc.path)
+                    throw eisdir("read", normalize(path));
+                const entry = await this.#repositoryEntry(loc.slug, loc.repository, loc.path);
+                if (!entry)
+                    throw enoent("open", normalize(path));
+                if (entry.kind === "directory")
+                    throw eisdir("read", normalize(path));
+                if (entry.kind === "submodule") {
+                    return `Submodule ${loc.path}\nRepository: ${loc.repository}\n`;
+                }
+                try {
+                    return await this.#client.readRepositoryFile(loc.slug, loc.repository, loc.path);
+                }
+                catch (e) {
+                    throw fromApi(e, "open", normalize(path));
+                }
+            }
             case "pullFile":
                 try {
                     return await this.#client.readPull(loc.slug, loc.number);
@@ -416,6 +518,27 @@ export class SforaFs {
                 catch (e) {
                     throw fromApi(e, "open", normalize(path));
                 }
+            case "planFile":
+                try {
+                    return await this.#client.readPlan(loc.slug);
+                }
+                catch (e) {
+                    throw fromApi(e, "open", normalize(path));
+                }
+            case "mapFile":
+                try {
+                    return await this.#client.readMap(loc.slug);
+                }
+                catch (e) {
+                    throw fromApi(e, "open", normalize(path));
+                }
+            case "asksFile":
+                try {
+                    return await this.#client.readAsks(loc.slug);
+                }
+                catch (e) {
+                    throw fromApi(e, "open", normalize(path));
+                }
             case "root":
             case "projectsDir":
             case "inboxDir":
@@ -423,6 +546,9 @@ export class SforaFs {
             case "projectDir":
             case "postsDir":
             case "docsDir":
+            case "libraryDir":
+            case "filesDir":
+            case "repositoriesDir":
             case "pullsDir":
             case "boardDir":
             case "boardColumnDir":
@@ -449,6 +575,10 @@ export class SforaFs {
         if (loc.kind === "inboxFile" || loc.kind === "meFile") {
             throw eacces("open", norm);
         }
+        // asks.md is a read-only projection — claims go through the asks API.
+        if (loc.kind === "asksFile") {
+            throw eacces("open", norm);
+        }
         if (loc.kind === "linksFile") {
             try {
                 await this.#client.setProjectLinks(loc.slug, toText(content));
@@ -458,6 +588,17 @@ export class SforaFs {
             }
             return;
         }
+        // plan.md: the PUT edits `## the goal` only; the server ignores (and
+        // names) every generated section, so a read-modify-write is always safe.
+        if (loc.kind === "planFile") {
+            try {
+                await this.#client.writePlan(loc.slug, toText(content));
+            }
+            catch (e) {
+                throw fromApi(e, "open", norm);
+            }
+            return;
+        }
         if (loc.kind === "root" ||
             loc.kind === "projectsDir" ||
             loc.kind === "inboxDir" ||
@@ -465,12 +606,21 @@ export class SforaFs {
             loc.kind === "projectDir" ||
             loc.kind === "postsDir" ||
             loc.kind === "docsDir" ||
+            loc.kind === "libraryDir" ||
+            loc.kind === "filesDir" ||
+            loc.kind === "repositoriesDir" ||
             loc.kind === "pullsDir" ||
             loc.kind === "boardDir" ||
             loc.kind === "boardColumnDir" ||
             loc.kind === "publicDir") {
             throw eisdir("open", norm);
         }
+        // map.md is derived from the board and refuses writes server-side (405);
+        // fail locally with the same message so an agent learns the write doors
+        // without a round trip.
+        if (loc.kind === "mapFile") {
+            throw eacces("open", norm);
+        }
         if (loc.kind === "postFile") {
             try {
                 await this.#client.writePost(loc.slug, loc.dir, loc.filename, toText(content));
@@ -481,6 +631,16 @@ export class SforaFs {
             this.#invalidate(loc.slug, loc.dir);
             return;
         }
+        if (loc.kind === "docFile") {
+            try {
+                await this.#client.writeNote(loc.slug, loc.filename, toText(content));
+            }
+            catch (e) {
+                throw fromApi(e, "open", norm);
+            }
+            this.#invalidateNotes(loc.slug);
+            return;
+        }
         if (loc.kind === "boardCardFile") {
             try {
                 const res = await this.#client.writeCard(loc.slug, loc.column, loc.filename, toText(content));
@@ -520,8 +680,14 @@ export class SforaFs {
                 case "projectDir":
                 case "postsDir":
                 case "docsDir":
+                case "libraryDir":
+                case "filesDir":
+                case "repositoriesDir":
                 case "pullsDir":
                 case "boardDir":
+                case "planFile":
+                case "mapFile":
+                case "asksFile":
                     return await this.#projectExists(loc.slug);
                 case "publicDir":
                 case "roadmapFile":
@@ -536,6 +702,10 @@ export class SforaFs {
                         undefined;
                 case "docFile":
                     return (await this.#matchNote(loc.slug, loc.filename)) !== undefined;
+                case "artifactFile":
+                    return (await this.#listArtifacts(loc.slug)).some((artifact) => artifact.name === loc.filename);
+                case "repositoryPath":
+                    return (await this.#repositoryEntry(loc.slug, loc.repository, loc.path)) !== undefined;
                 case "pullFile":
                     return (await this.#matchPull(loc.slug, loc.number)) !== undefined;
                 case "boardCardFile":
@@ -583,12 +753,18 @@ export class SforaFs {
                 case "meFile":
                     return this.#fileStat(new Date());
                 case "linksFile":
+                case "planFile":
+                case "mapFile":
+                case "asksFile":
                     if (!(await this.#projectExists(loc.slug)))
                         throw enoent("stat", norm);
                     return this.#fileStat(new Date());
                 case "projectDir":
                 case "postsDir":
                 case "docsDir":
+                case "libraryDir":
+                case "filesDir":
+                case "repositoriesDir":
                 case "pullsDir":
                 case "boardDir":
                     if (!(await this.#projectExists(loc.slug)))
@@ -625,6 +801,20 @@ export class SforaFs {
                         throw enoent("stat", norm);
                     return this.#fileStat(new Date(note.lastEditedAt || Date.now()));
                 }
+                case "artifactFile": {
+                    const artifact = (await this.#listArtifacts(loc.slug)).find((candidate) => candidate.name === loc.filename);
+                    if (!artifact)
+                        throw enoent("stat", norm);
+                    return this.#fileStat(new Date(artifact.uploadedAt || Date.now()), artifact.size);
+                }
+                case "repositoryPath": {
+                    const entry = await this.#repositoryEntry(loc.slug, loc.repository, loc.path);
+                    if (!entry)
+                        throw enoent("stat", norm);
+                    return entry.kind === "directory"
+                        ? this.#dirStat()
+                        : this.#fileStat(new Date(), "size" in entry ? entry.size ?? 0 : 0);
+                }
                 case "pullFile": {
                     const pull = await this.#matchPull(loc.slug, loc.number);
                     if (!pull)
@@ -683,10 +873,13 @@ export class SforaFs {
                         throw enoent("scandir", norm);
                     }
                     const entries = [
+                        dirent("asks.md", false),
                         dirent("board", true),
-                        dirent("docs", true),
                         dirent("drafts", true),
+                        dirent("library", true),
                         dirent("links.md", false),
+                        dirent("plan.md", false),
+                        dirent("map.md", false),
                         dirent("posts", true),
                         dirent("pulls", true),
                     ];
@@ -696,6 +889,14 @@ export class SforaFs {
                     }
                     return entries;
                 }
+                case "libraryDir":
+                    if (!(await this.#projectExists(loc.slug)))
+                        throw enoent("scandir", norm);
+                    return [
+                        dirent("documents", true),
+                        dirent("files", true),
+                        dirent("repositories", true),
+                    ];
                 case "postsDir": {
                     const entries = await this.#listEntries(loc.slug, loc.dir);
                     return entries.map((e) => dirent(e.filename, false));
@@ -707,6 +908,35 @@ export class SforaFs {
                     const notes = await this.#listNotes(loc.slug);
                     return notes.map((n) => dirent(n.filename, false));
                 }
+                case "filesDir": {
+                    if (!(await this.#projectExists(loc.slug)))
+                        throw enoent("scandir", norm);
+                    return (await this.#listArtifacts(loc.slug)).map((artifact) => dirent(artifact.name, false));
+                }
+                case "repositoriesDir": {
+                    if (!(await this.#projectExists(loc.slug)))
+                        throw enoent("scandir", norm);
+                    return (await this.#listRepositories(loc.slug)).map((repository) => dirent(repository.dirname, true));
+                }
+                case "repositoryPath": {
+                    const current = await this.#repositoryEntry(loc.slug, loc.repository, loc.path);
+                    if (!current)
+                        throw enoent("scandir", norm);
+                    if (current.kind !== "directory")
+                        throw enotdir("scandir", norm);
+                    const prefix = loc.path ? `${loc.path}/` : "";
+                    const children = new Map();
+                    for (const entry of (await this.#repositoryTree(loc.slug, loc.repository)).entries) {
+                        if (!entry.path.startsWith(prefix) || entry.path === loc.path)
+                            continue;
+                        const rest = entry.path.slice(prefix.length);
+                        const [name, ...tail] = rest.split("/");
+                        if (!name)
+                            continue;
+                        children.set(name, tail.length > 0 || entry.kind === "directory");
+                    }
+                    return [...children].map(([name, isDir]) => dirent(name, isDir));
+                }
                 case "pullsDir": {
                     if (!(await this.#projectExists(loc.slug))) {
                         throw enoent("scandir", norm);
@@ -743,9 +973,12 @@ export class SforaFs {
                 case "meFile":
                 case "postFile":
                 case "docFile":
+                case "artifactFile":
                 case "pullFile":
                 case "boardCardFile":
                 case "roadmapFile":
+                case "planFile":
+                case "asksFile":
                     throw enotdir("scandir", norm);
                 default:
                     throw enoent("scandir", norm);
@@ -772,6 +1005,9 @@ export class SforaFs {
             case "projectDir":
             case "postsDir":
             case "docsDir":
+            case "libraryDir":
+            case "filesDir":
+            case "repositoriesDir":
             case "pullsDir":
             case "boardDir":
             case "publicDir":
@@ -858,12 +1094,32 @@ export class SforaFs {
             }
             case "inboxFile":
             case "meFile":
-            case "docFile":
+            case "artifactFile":
+            case "repositoryPath":
             case "pullFile":
             case "roadmapFile":
-                // Read-only surfaces (notes aren't deletable through the fs yet; the
-                // roadmap is a projection; pulls are owned by GitHub).
+            case "planFile":
+            case "asksFile":
+                // Uploaded files and repositories are read-only projections; the
+                // roadmap and pulls are owned by their source systems; the plan and
+                // asks are generated views that can't be unlinked.
                 throw eacces("unlink", norm);
+            case "docFile": {
+                const note = await this.#matchNote(loc.slug, loc.filename);
+                if (!note) {
+                    if (options?.force)
+                        return;
+                    throw enoent("unlink", norm);
+                }
+                try {
+                    await this.#client.deleteNote(loc.slug, loc.filename);
+                }
+                catch (e) {
+                    throw fromApi(e, "unlink", norm);
+                }
+                this.#invalidateNotes(loc.slug);
+                return;
+            }
             case "root":
             case "projectsDir":
             case "inboxDir":
@@ -871,6 +1127,9 @@ export class SforaFs {
             case "projectDir":
             case "postsDir":
             case "docsDir":
+            case "libraryDir":
+            case "filesDir":
+            case "repositoriesDir":
             case "pullsDir":
             case "boardDir":
             case "publicDir":
@@ -982,9 +1241,16 @@ export class SforaFs {
         ]);
         for (const slug of this.#projectSlugs) {
             paths.add(`/projects/${slug}`);
+            paths.add(`/projects/${slug}/plan.md`);
+            paths.add(`/projects/${slug}/asks.md`);
             paths.add(`/projects/${slug}/posts`);
             paths.add(`/projects/${slug}/drafts`);
             paths.add(`/projects/${slug}/docs`);
+            paths.add(`/projects/${slug}/artifacts`);
+            paths.add(`/projects/${slug}/library`);
+            paths.add(`/projects/${slug}/library/documents`);
+            paths.add(`/projects/${slug}/library/files`);
+            paths.add(`/projects/${slug}/library/repositories`);
             paths.add(`/projects/${slug}/pulls`);
             paths.add(`/projects/${slug}/board`);
             // `public/` is only real for boards known to be shared.

package/dist/api-client.d.ts

@@ -38,6 +38,35 @@ export interface Note {
     title: string;
     lastEditedAt: number;
 }
+/** An uploaded project file under the unified Library. */
+export interface Artifact {
+    name: string;
+    mimeType: string;
+    size: number;
+    uploadedBy: string | null;
+    uploadedAt: number;
+    url: string | null;
+}
+/** A GitHub repository attached to a project. Repository content is read-only. */
+export interface Repository {
+    projectRepoId: string;
+    dirname: string;
+    owner: string;
+    repo: string;
+    defaultBranch: string;
+}
+export interface RepositoryTreeEntry {
+    path: string;
+    kind: "file" | "directory" | "submodule";
+    size?: number;
+}
+export interface RepositoryTree {
+    owner: string;
+    repo: string;
+    ref: string;
+    truncated: boolean;
+    entries: RepositoryTreeEntry[];
+}
 /**
  * A pull request entry. Mirrors a row of `GET …/pulls`. Read-only — the source
  * of truth is GitHub; sfora syncs these so agents can see the code work
@@ -121,6 +150,16 @@ export declare class SforaApiClient {
     getProjectLinks(slug: string): Promise<string>;
     /** `PUT …/links.md` — replace the project's links from a markdown list. */
     setProjectLinks(slug: string, markdown: string): Promise<void>;
+    /** `GET …/plan.md` — the project's plan (goal + question buckets). */
+    readMap(slug: string): Promise<string>;
+    readPlan(slug: string): Promise<string>;
+    /**
+     * `PUT …/plan.md` — set the goal. Only the `## the goal` section is
+     * honored; the server names everything it ignored in `ignoredSections`.
+     */
+    writePlan(slug: string, markdown: string): Promise<void>;
+    /** `GET …/asks.md` — coordination asks (read-only projection). */
+    readAsks(slug: string): Promise<string>;
     /**
      * `GET …/posts` or `…/drafts`. `scheduled` lists drafts that have a
      * (future) `scheduledFor` set.
@@ -128,7 +167,7 @@ export declare class SforaApiClient {
     listPosts(projectSlug: string, kind?: PostKind): Promise<Entry[]>;
     /** `GET …/posts/:filename.md` (or `…/drafts/…`). Returns the raw markdown body. */
     readPost(projectSlug: string, filename: string, kind?: PostKind): Promise<string>;
-    /** `PUT …/(posts|drafts)/:filename.md` — create or update from a markdown file. */
+    /** Create a post or upsert a mutable draft from a Markdown file. */
     writePost(projectSlug: string, kind: PostKind, filename: string, markdown: string): Promise<WriteResult>;
     /** `DELETE …/(posts|drafts)/:filename.md` — soft-deletes the matched post. */
     deletePost(projectSlug: string, kind: PostKind, filename: string): Promise<void>;
@@ -136,6 +175,13 @@ export declare class SforaApiClient {
     listNotes(projectSlug: string): Promise<Note[]>;
     /** `GET …/docs/:filename.md`. Returns the raw markdown body. */
     readNote(projectSlug: string, filename: string): Promise<string>;
+    writeNote(projectSlug: string, filename: string, markdown: string): Promise<WriteResult>;
+    deleteNote(projectSlug: string, filename: string): Promise<void>;
+    listArtifacts(projectSlug: string): Promise<Artifact[]>;
+    readArtifact(projectSlug: string, filename: string): Promise<string>;
+    listRepositories(projectSlug: string): Promise<Repository[]>;
+    getRepositoryTree(projectSlug: string, dirname: string): Promise<RepositoryTree>;
+    readRepositoryFile(projectSlug: string, dirname: string, path: string): Promise<string>;
     /** `GET …/pulls` — the project's synced pull requests, open first. */
     listPulls(projectSlug: string): Promise<Pull[]>;
     /**

package/dist/api-client.js

@@ -102,6 +102,25 @@ export class SforaApiClient {
     async setProjectLinks(slug, markdown) {
         await this.#request("PUT", `/v1/fs/projects/${encodeURIComponent(slug)}/links.md`, markdown);
     }
+    /** `GET …/plan.md` — the project's plan (goal + question buckets). */
+    // The map as a file: derived, read-only (a PUT is refused server-side).
+    async readMap(slug) {
+        return this.#text(`/v1/fs/projects/${encodeURIComponent(slug)}/map.md`);
+    }
+    async readPlan(slug) {
+        return this.#text(`/v1/fs/projects/${encodeURIComponent(slug)}/plan.md`);
+    }
+    /**
+     * `PUT …/plan.md` — set the goal. Only the `## the goal` section is
+     * honored; the server names everything it ignored in `ignoredSections`.
+     */
+    async writePlan(slug, markdown) {
+        await this.#request("PUT", `/v1/fs/projects/${encodeURIComponent(slug)}/plan.md`, markdown);
+    }
+    /** `GET …/asks.md` — coordination asks (read-only projection). */
+    async readAsks(slug) {
+        return this.#text(`/v1/fs/projects/${encodeURIComponent(slug)}/asks.md`);
+    }
     /**
      * `GET …/posts` or `…/drafts`. `scheduled` lists drafts that have a
      * (future) `scheduledFor` set.
@@ -123,7 +142,7 @@ export class SforaApiClient {
         const file = encodeURIComponent(filename);
         return this.#text(`/v1/fs/projects/${slug}/${base}/${file}`);
     }
-    /** `PUT …/(posts|drafts)/:filename.md` — create or update from a markdown file. */
+    /** Create a post or upsert a mutable draft from a Markdown file. */
     async writePost(projectSlug, kind, filename, markdown) {
         const base = routeBase(kind);
         const slug = encodeURIComponent(projectSlug);
@@ -143,14 +162,52 @@ export class SforaApiClient {
     /** `GET …/docs` — the project's notes, most-recently-edited first. */
     async listNotes(projectSlug) {
         const slug = encodeURIComponent(projectSlug);
-        const data = await this.#json(`/v1/fs/projects/${slug}/docs`);
+        const data = await this.#json(`/v1/fs/projects/${slug}/library/documents`);
         return data.docs ?? [];
     }
     /** `GET …/docs/:filename.md`. Returns the raw markdown body. */
     async readNote(projectSlug, filename) {
         const slug = encodeURIComponent(projectSlug);
         const file = encodeURIComponent(filename);
-        return this.#text(`/v1/fs/projects/${slug}/docs/${file}`);
+        return this.#text(`/v1/fs/projects/${slug}/library/documents/${file}`);
+    }
+    async writeNote(projectSlug, filename, markdown) {
+        const slug = encodeURIComponent(projectSlug);
+        const file = encodeURIComponent(filename);
+        const res = await this.#request("PUT", `/v1/fs/projects/${slug}/library/documents/${file}`, markdown);
+        return (await res.json());
+    }
+    async deleteNote(projectSlug, filename) {
+        const slug = encodeURIComponent(projectSlug);
+        const file = encodeURIComponent(filename);
+        await this.#request("DELETE", `/v1/fs/projects/${slug}/library/documents/${file}`);
+    }
+    // ─── Unified project Library ────────────────────────────────────
+    async listArtifacts(projectSlug) {
+        const slug = encodeURIComponent(projectSlug);
+        const data = await this.#json(`/v1/fs/projects/${slug}/library/files`);
+        return data.artifacts ?? [];
+    }
+    async readArtifact(projectSlug, filename) {
+        const slug = encodeURIComponent(projectSlug);
+        const file = encodeURIComponent(filename);
+        return this.#text(`/v1/fs/projects/${slug}/library/files/${file}`);
+    }
+    async listRepositories(projectSlug) {
+        const slug = encodeURIComponent(projectSlug);
+        const data = await this.#json(`/v1/fs/projects/${slug}/library/repositories`);
+        return data.repositories ?? [];
+    }
+    async getRepositoryTree(projectSlug, dirname) {
+        const slug = encodeURIComponent(projectSlug);
+        const repo = encodeURIComponent(dirname);
+        return this.#json(`/v1/fs/projects/${slug}/library/repositories/${repo}`);
+    }
+    async readRepositoryFile(projectSlug, dirname, path) {
+        const slug = encodeURIComponent(projectSlug);
+        const repo = encodeURIComponent(dirname);
+        const file = path.split("/").map(encodeURIComponent).join("/");
+        return this.#text(`/v1/fs/projects/${slug}/library/repositories/${repo}/${file}`);
     }
     // ─── Pull requests (read-only) ───────────────────────────────────
     /** `GET …/pulls` — the project's synced pull requests, open first. */