favorites: list/add/rm + ★ in ls

src/api.ts

@@ -57,6 +57,11 @@ export class Api {
   pull = (id: string) => this.req(`/api/docs/${encodeURIComponent(id)}/pull`).then((r) => r.json())
   readContent = (id: string) => this.req(`/api/docs/${encodeURIComponent(id)}/content`).then((r) => r.text())
   listShared = () => this.req('/api/docs/shared').then((r) => r.json())
+  listFavorites = () => this.req('/api/docs/favorites').then((r) => r.json())
+  favorite = (id: string) =>
+    this.req(`/api/docs/${encodeURIComponent(id)}/favorite`, { method: 'PUT', body: '{}' }).then((r) => r.json())
+  unfavorite = (id: string) =>
+    this.req(`/api/docs/${encodeURIComponent(id)}/favorite`, { method: 'DELETE' }).then((r) => r.json())
   history = (id: string) => this.req(`/api/docs/${encodeURIComponent(id)}/versions`).then((r) => r.json())
   versionContent = (id: string, n: number) => this.req(`/api/docs/${encodeURIComponent(id)}/versions/${n}`).then((r) => r.text())
   revert = (id: string, version: number, message?: string) =>

src/cli.ts

@@ -160,19 +160,23 @@ program
       return void process.stdout.write(`${JSON.stringify({ docs, workspaces, shared })}\n`)
     }
     const wsName = new Map<string, string>(workspaces.map((w: { id: string; name: string }) => [w.id, w.name]))
-    const byWs = new Map<string, { id: string; title: string }[]>()
-    for (const d of docs) {
+    type LsDoc = { id: string; title: string; workspace_id?: string | null; favorite?: boolean; owner_email?: string }
+    const byWs = new Map<string, LsDoc[]>()
+    for (const d of docs as LsDoc[]) {
       const k = d.workspace_id ?? 'none'
       ;(byWs.get(k) ?? byWs.set(k, []).get(k)!).push(d)
     }
     if (docs.length === 0 && shared.length === 0) return void process.stdout.write('No documents.\n')
+    // A leading ★ marks favorites (plain space keeps ids aligned).
+    const star = (d: LsDoc) => (d.favorite ? '★' : ' ')
     for (const [wid, list] of byWs) {
       process.stdout.write(`\n${wsName.get(wid) ?? 'Workspace'}\n`)
-      for (const d of list) process.stdout.write(`  ${d.id}  ${d.title}\n`)
+      for (const d of list) process.stdout.write(`  ${star(d)} ${d.id}  ${d.title}\n`)
     }
     if (shared.length > 0) {
       process.stdout.write(`\nShared\n`)
-      for (const d of shared) process.stdout.write(`  ${d.id}  ${d.title}  (${d.owner_email ?? 'shared'})\n`)
+      for (const d of shared as LsDoc[])
+        process.stdout.write(`  ${star(d)} ${d.id}  ${d.title}  (${d.owner_email ?? 'shared'})\n`)
     }
   })
 
@@ -380,6 +384,46 @@ program
     )
   })
 
+// ---- favorites (starred docs) ----
+const fav = program.command('favorites').alias('favs').description('List and manage your favorite (starred) docs')
+
+fav
+  .command('list', { isDefault: true })
+  .description('List your favorite docs')
+  .action(async () => {
+    const { docs } = await api()
+      .listFavorites()
+      .catch((e: ApiError) => fail(e.code, e.message))
+    if (program.opts().json) return void process.stdout.write(`${JSON.stringify(docs)}\n`)
+    if (docs.length === 0) {
+      return void process.stdout.write('No favorites yet. Star one with `mdocs favorites add <doc>`.\n')
+    }
+    for (const d of docs) process.stdout.write(`  ★ ${d.id}  ${d.title}\n`)
+  })
+
+fav
+  .command('add <doc>')
+  .description('Add a doc to your favorites')
+  .action(async (docId: string) => {
+    await api()
+      .favorite(docId)
+      .catch((e: ApiError) => fail(e.code, e.message))
+    if (program.opts().json) return void process.stdout.write(`${JSON.stringify({ id: docId, favorite: true })}\n`)
+    process.stdout.write(`★ Favorited ${docId}\n`)
+  })
+
+fav
+  .command('rm <doc>')
+  .alias('remove')
+  .description('Remove a doc from your favorites')
+  .action(async (docId: string) => {
+    await api()
+      .unfavorite(docId)
+      .catch((e: ApiError) => fail(e.code, e.message))
+    if (program.opts().json) return void process.stdout.write(`${JSON.stringify({ id: docId, favorite: false })}\n`)
+    process.stdout.write(`☆ Unfavorited ${docId}\n`)
+  })
+
 // ---- trash (recently deleted) ----
 const daysLeft = (deletedAt: string, retentionDays: number): string => {
   const days = Math.ceil((new Date(deletedAt).getTime() + retentionDays * 86400_000 - Date.now()) / 86400_000)

src/instructions.ts

@@ -28,7 +28,8 @@ stable JSON when you pass --json. Exit codes are meaningful (see below).
 
 ## Commands
 - mdocs ls [--json]
-    List accessible docs. JSON: [{"id","title","workspaceId","createdAt","updatedAt"}]
+    List accessible docs. A leading ★ marks favorites. JSON includes "favorite".
+    [{"id","title","workspaceId","createdAt","updatedAt","favorite"}]
 - mdocs workspaces [--json]   (alias: ws; same as "ws list")
     List your workspaces with ids (for "new --workspace").
 - mdocs ws create <name> [--json]
@@ -55,6 +56,12 @@ stable JSON when you pass --json. Exit codes are meaningful (see below).
 - mdocs share <doc-id> --link [--role viewer|editor]
     Create a shareable link (anyone signed in who opens it gets access). Prints
     the URL. JSON: {"url","role"}.
+- mdocs favorites [list] [--json]   (alias: favs)
+    List your favorite (starred) docs. JSON: same shape as "ls" rows.
+- mdocs favorites add <doc-id>
+    Star a doc so it shows under Favorites (in the app and "mdocs favorites").
+- mdocs favorites rm <doc-id>   (alias: remove)
+    Unstar a doc.
 - mdocs history <doc-id> [--json]   (alias: log)
     Show version history: each version's number, time, author, source, message.
     JSON: [{"n","createdAt","authorEmail","source","message","contentHash"}]

src/skill.ts

@@ -33,7 +33,7 @@ it — it lists every command, flag, JSON shape, and exit code:
     mdocs push doc.md --message "why" # 3-way merge back; re-pull if it conflicts
 
 Other commands: mdocs ws (list/create workspaces), mdocs new (create a doc from a
-file), mdocs history / revert, mdocs whoami.
+file), mdocs history / revert, mdocs favorites (star/list docs), mdocs whoami.
 
 ## Auth
 - Headless/agent: set MDOCS_TOKEN (a user generates it) and optionally MDOCS_SERVER.