--- name: folio-planning-share description: Upload planning, research, design, or project document bundles to Folio and return a private editable share link; later inspect the baseline diff or download the edited ZIP. Use when someone asks to put plans online, share a folder or ZIP for review, hand documents to another human or agent, create a browsable research pack, or pull collaborative edits back from Folio. compatibility: Requires curl and a ZIP utility; jq is recommended for reading responses. Uploads require a Folio account (Better Auth magic link). metadata: version: "1.0.0" last-reviewed: "2026-08-04" --- # Folio planning handoff Use Folio to make a folder-shaped collection of planning or research documents browsable and editable through a capability link. ## Default workflow 1. Confirm which files belong in the handoff and choose a clear collection title. 2. Check the bundle before upload. Exclude credentials, private keys, environment files, personal data, and unrelated secrets. 3. Preserve relative paths while creating a ZIP. Keep within 50 files, 10 MB unpacked, and 12 MB compressed. 4. Choose an expiry from 1 to 30 days. Use 7 days when the user does not specify one. 5. Sign in to Folio (or create a Folio API key) before uploading. 6. Upload the ZIP to Folio. 7. Read the `shareUrl`, `token`, `expiresAt`, and file metadata from the response. 8. Return the share URL, collection title, file count, and expiry. Say clearly that anyone holding the link can view every shared article and file, edit supported text formats, and download the collection until then. 9. Keep the token available for requested follow-up work such as checking changes or downloading the edited ZIP. Do not reveal it separately unless needed. ## Upload Set the service URL: ```sh FOLIO_BASE_URL="https://folio.tom8.to" ``` Create the archive from the parent directory so the intended folder structure is retained: ```sh zip -r planning-pack.zip planning-pack ``` For a browser session, sign in at `https://folio.tom8.to/?auth=1&return_to=/?new=1` first. For an agent, set `FOLIO_AUTH_TOKEN` to a Folio API key and send it as `X-Folio-Auth-Token`: ```sh curl --fail --silent --show-error \ -F "archive=@planning-pack.zip" \ -F "title=Planning pack" \ -F "expiresInDays=7" \ -H "X-Folio-Auth-Token: $FOLIO_AUTH_TOKEN" \ "$FOLIO_BASE_URL/api/import" ``` Capture the JSON response in a temporary file or in memory. Use `jq -r '.shareUrl'` and `jq -r '.token'` when jq is available. Treat both values as capability secrets; the share URL embeds access to the collection. ## Report the handoff Use this compact shape: ```text Planning pack is ready: files, preserving the uploaded folder structure. Anyone with this link can view every shared article and file, edit supported text formats, and download the collection until . ``` Uploads are account-gated to prevent abuse. Folio uses Better Auth with Resend magic links; it does not require a ChatGPT identity. Shared collections remain anonymous to view and edit: access is possession of the unguessable link. API keys are created for an authenticated Folio user. The collection URL has the form `/folder//`. To focus a nested file, append its URL-encoded path: `/folder//research/findings.md`. The browser also updates this path as files are opened. A focused document URL still grants access to the entire collection; never describe it as document-only access. To focus source lines, append `?s=L4` for one line or `?s=L4:L6` for an inclusive range. The browser creates this query when someone clicks a line number in Source view and Shift-clicks another. Use a line-selection URL when the user wants collaborators to land on a specific passage, but state that it still grants full collection access. ## Pull edits back Check which files differ from the upload baseline: ```sh curl --fail --silent --show-error \ -H "Authorization: Bearer $FOLIO_TOKEN" \ "$FOLIO_BASE_URL/api/diff" ``` Download the current collection: ```sh curl --fail --silent --show-error \ -H "Authorization: Bearer $FOLIO_TOKEN" \ "$FOLIO_BASE_URL/api/export" \ -o edited-planning-pack.zip ``` Keep the original local archive unless the user asks to replace it. Inspect the downloaded ZIP safely before copying edits into a working directory. ## Additional operations Send `Authorization: Bearer $FOLIO_TOKEN` for every operation after import. To replace a collection, send both the capability bearer and the Folio API-key header: `Authorization: Bearer $FOLIO_TOKEN` and `X-Folio-Auth-Token: $FOLIO_AUTH_TOKEN`. - `GET /api/collection` lists files and their changed flags. - `GET /api/file?path=` downloads one current file. - `PUT /api/file?path=` replaces an editable text, Markdown, or HTML file with the request body. - `GET /api/original?path=` retrieves baseline bytes. - `PATCH /api/collection` with `{ "title": "New title" }` renames the collection. - Collection expiry is fixed at initial upload. There is no expiry-extension operation; replacing files preserves the existing expiry and cannot extend it. - `POST /api/import` with the bearer token replaces all files and resets the baseline. Do this only when the user explicitly asks to replace the collection. Read `/llms.txt` for the concise machine-facing reference and `/api/docs` for the endpoint list. ## Failure handling - Stop and report the server's error for invalid ZIPs or rejected limits. - Never weaken path-safety checks or retry by flattening folders without asking. - Never post the share URL to a public destination unless the user explicitly requests that audience. - If the token is unavailable, ask for the original share URL or a fresh upload; do not try to derive or guess identifiers.