---
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.
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. Upload the ZIP to Folio.
6. Read the `shareUrl`, `token`, `expiresAt`, and file metadata from the response.
7. 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.
8. 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-private-archive.solar-frog-9501.chatgpt.site"
```

Create the archive from the parent directory so the intended folder structure is retained:

```sh
zip -r planning-pack.zip planning-pack
```

Upload it:

```sh
curl --fail --silent --show-error \
  -F "archive=@planning-pack.zip" \
  -F "title=Planning pack" \
  -F "expiresInDays=7" \
  "$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: <shareUrl>
<file-count> 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 <expiresAt>.
```

Do not claim that Folio provides user accounts, access revocation, or per-person permissions. Access is possession of the unguessable link.

The collection URL has the form `/folder/<token>/`. To focus a nested file, append its URL-encoded path: `/folder/<token>/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.

- `GET /api/collection` lists files and their changed flags.
- `GET /api/file?path=<url-encoded-path>` downloads one current file.
- `PUT /api/file?path=<url-encoded-path>` replaces an editable text, Markdown, or HTML file with the request body.
- `GET /api/original?path=<url-encoded-path>` retrieves baseline bytes.
- `PATCH /api/collection` with `{ "title": "New title" }` renames the collection.
- `PATCH /api/collection` with `{ "expiresInDays": 14 }` resets expiry to the chosen period from now; the value must be from 1 to 30.
- `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.