# Write

Write is a publishing platform. Each blog is a workspace of folders, and every
item in a folder is a Markdown file with metadata frontmatter and a body.
Folder modes:

- blog: public writing (kinds: article, media_post, video_post)
- notes: private notes, always unlisted
- bookmarks: private saved links, always unlisted

## Public surfaces, per blog

Base URL: https://write.ramine.net/@{username}

- {base}/llms.txt: published posts with summaries and Markdown file links
- {base}/folder.json: manifest of published items, sha256 hash per file
- {base}/posts.json: published posts as JSON
- {base}/{slug}/index.md: one post as its Markdown file
- {base}/feed.xml, {base}/atom.xml, {base}/feed.json: feeds
- {base}/sitemap.xml: sitemap

## Authenticated MCP surface

MCP Streamable HTTP endpoint: https://write.ramine.net/api/mcp

The endpoint advertises OAuth discovery from its unauthenticated 401 response.
The click-to-approve flow uses authorization code with PKCE S256. Clients
should request the least privilege they need:

- read: 8 workspace inspection tools
- sync: all 26 tools, including access management and mutations

A client requesting both advertised scopes receives effective sync access.

OAuth access tokens begin with wsk_ and expire after 3,600 seconds. Each token
exchange also returns a wrt_ refresh token. Refresh tokens rotate on every use;
reusing a consumed refresh token revokes the complete token family. Refresh
access has a 180-day absolute lifetime and a 30-day inactivity lifetime.

Clients without OAuth can create a manual sync-scoped wsk_ bearer token at
https://write.ramine.net/connect. Manual tokens remain valid until revoked. Send access tokens
as "Authorization: Bearer wsk_...".

The shared 26 tools are:

- Read: get_workspace, list_folders, list_items, read_item, search, list_trash, list_comments, list_access
- Mutations: create_item, update_item, append_to_item, set_item_status, move_item, delete_item, restore_item, add_item_asset, remove_item_asset, recapture_bookmark, add_comment, set_comment_resolved, create_folder, rename_folder, delete_folder, restore_folder, set_access, revoke_access

delete_item and delete_folder are soft deletes. list_trash exposes restorable
items and folder restoration units. restore_item and restore_folder restore
them. A restored published item can become public again. There is no
permanent-delete MCP tool.

The command surface also manages direct workspace, folder, and item access;
collaboration comments; bookmark recapture; and item cover and asset references.
Every mutation is audited.

New items are drafts. Notes and bookmarks cannot publish. Existing-item writes
should send the latest if_match_hash; stale writes are rejected. Every mutation
is audited.

## Sync API and OpenAPI actions

Sync API: https://write.ramine.net/api/sync/v1

The sync API requires the sync scope for every route. It provides workspace and
folder manifests, file GET/POST/PUT/PATCH/DELETE, changes, assets, and bookmark
capture. Existing-file mutations use If-Match conflict checks. DELETE moves an
item to Trash.

OpenAPI actions: https://write.ramine.net/openapi.json

The OpenAPI document is a smaller sync-backed action surface, not the complete
26-tool MCP contract.

## In-app assistant

Write for Mac uses Apple's on-device Foundation Models runtime and calls the
same 26 workspace commands directly through the signed-in page. It does not use
Write's MCP endpoint. The plain web app has no assistant model fallback.
OpenAI and Anthropic are not implemented as in-app providers; they can connect
as external MCP clients.

Human setup: https://write.ramine.net/docs/ai. Approval flow: https://write.ramine.net/api/mcp advertises OAuth from its 401.