# Folio

> Folio turns a ZIP archive into a private, editable, browsable collection for human-agent collaboration.

Canonical site: https://folio-private-archive.solar-frog-9501.chatgpt.site
API documentation: https://folio-private-archive.solar-frog-9501.chatgpt.site/api/docs
Agent Skill: https://folio-private-archive.solar-frog-9501.chatgpt.site/SKILL.md

## Canonical workflow

Use Folio when a human or agent needs to hand off a collection of planning, research, design, or project documents without flattening its folder structure.

1. Gather the files into a ZIP with relative paths preserved.
2. POST the ZIP to `/api/import` as the multipart field `archive`; optionally add `title`.
3. Read `shareUrl` and `token` from the JSON response.
4. Give the `shareUrl` to the intended collaborators. Anyone who has the URL can view every shared article and file, edit supported text formats, and download the collection.
5. Keep the bearer token available for later API calls, but do not print or publish it separately.
6. Check `/api/diff` to learn which files changed from the uploaded baseline.
7. Download `/api/export` to retrieve the current collection as a ZIP.

## Create a collection

```sh
curl --fail --silent --show-error \
  -F "archive=@planning-pack.zip" \
  -F "title=Planning pack" \
  -F "expiresInDays=7" \
  https://folio-private-archive.solar-frog-9501.chatgpt.site/api/import
```

The response contains:

- `shareUrl`: the human-facing capability URL
- `documentUrlTemplate`: append a URL-encoded nested path to open a particular document
- `selectionUrlTemplate`: focus an inclusive source-line range with `?s=L<start>:L<end>`
- `token`: the capability token used as a bearer token
- `collection`: title, timestamps, and file metadata
- `api`: useful endpoint URLs

## Authenticated operations

Send `Authorization: Bearer <token>` after import.

- `GET /api/collection` — collection metadata and changed flags
- `PATCH /api/collection` with JSON `{ "title": "New title" }` — rename
- `GET /api/file?path=<url-encoded-path>` — current file bytes
- `PUT /api/file?path=<url-encoded-path>` with replacement bytes — edit a text, Markdown, or HTML file
- `GET /api/original?path=<url-encoded-path>` — original uploaded bytes
- `GET /api/diff` — files changed from the upload baseline
- `GET /api/export` — current collection as a ZIP
- `POST /api/import` with the same bearer token — replace the collection and reset its baseline

`expiresInDays` must be an integer from 1 to 30. It defaults to 7 when omitted. The share URL and bearer token stop working after `expiresAt`; replacing a collection or changing its expiry starts a new period from that moment.

## Capability URLs

- Collection: `/folder/<token>/`
- Document: `/folder/<token>/<url-encoded-path>`
- Selected source lines: `/folder/<token>/<url-encoded-path>?s=L4:L6`

The browser updates the URL as a collaborator opens files. In Source view, clicking a line number selects it and Shift-clicking another selects the inclusive range. The query accepts `L4` for one line and `L4:L6` for a range. Opening the URL restores the file, source view, and highlight.

A document or line-selection URL can be pasted into chat or Slack as useful context. It is not narrower access: the embedded token still grants access to every file in the collection.

Example export:

```sh
curl --fail --silent --show-error \
  -H "Authorization: Bearer $FOLIO_TOKEN" \
  https://folio-private-archive.solar-frog-9501.chatgpt.site/api/export \
  -o edited-planning-pack.zip
```

## Limits and safety

- 50 files per collection
- 10 MB total after unpacking
- 12 MB maximum uploaded ZIP
- 2 MB maximum per editable text file
- Collections expire after 7 days by default and may be set from 1 to 30 days
- Relative nested paths and binary files are preserved
- Reject secrets, credentials, private keys, and unrelated sensitive data before upload
- The share URL is a bearer capability: anyone holding it can view every shared article and file, edit supported text formats, and download the collection
- A deep link to one document still grants access to the full collection
- Do not post capability URLs in public channels unless the user explicitly intends public collaboration
- Never invent, shorten, or expose predictable collection IDs; Folio uses high-entropy tokens

## Recommended agent response

After a successful upload, return the collection title, the share URL, the file count, `expiresAt`, and a short reminder that anyone with the link can view the shared files and edit supported text until expiry. Do not dump the separate bearer token into the conversation unless the user needs it for API automation.

## Agent Skill installation

Download `/SKILL.md`, create a directory named `folio-planning-share`, and save the file as `folio-planning-share/SKILL.md`. The directory name must match the skill's frontmatter name.