Portable, AI-native data sheets.
A sheet is a directory of plain files that AI agents read and write as
first-class users, that humans review later, and that travel as a tar
archive across machines.
my-sheet/
├── contract.yaml # required — ODCS subset
├── records.jsonl # required — one JSON object per line
├── derivations/ # optional — derivation files
├── scripts/ # optional — reusable scripts
├── skills/ # optional — packaged operating procedures
├── provenance.jsonl # append-only audit log
└── README.md # optional, with typed frontmatter
folio— Python SDK + CLI (init, validate, query, list, count, upsert, delete, materialize, status, provenance, serve, script, skill, export).folio-mcp— FastMCP server exposing the SDK as nine tools plus one MCP prompt per discovered skill (stdio or HTTP transport).folio-viewer— local-only FastAPI + React UI for human review.
User-facing documentation lives in apps/docs/ (Astro +
Starlight). Run it locally:
cd apps/docs
npm install
npm run dev # → http://127.0.0.1:4321/Or read the canonical sources directly:
- Design overview — the spec
- ADRs — architectural decisions
- Examples — five sheets covering four canonical use cases (customers + its customer-revenue sidecar, research-notes, research-memory, onboarding) — all run offline
uv tool install folio-kit # → installs the `folio` command
folio validate examples/customers
folio materialize examples/customers --actor agent:demo
folio serve examples/customers --port 3000 --actor agent:human
# → http://127.0.0.1:3000/Releases ship three artifact families. Pick the one that matches how you want to use Folio.
# from PyPI (preferred)
pipx install folio-kit
uv tool install folio-kit
# from a tagged GitHub Release wheel
pipx install https://github.com/nyuta01/folio/releases/download/vX.Y.Z/folio_kit-X.Y.Z-py3-none-any.whlThe PyPI distribution name is folio-kit; the wheel installs three
console scripts: folio, folio-mcp, folio-viewer. SHA-256
checksums for every release artifact are attached as SHA256SUMS.txt.
Download the installer for your platform from the latest release:
| Platform | Asset |
|---|---|
| macOS (Apple Silicon) | Folio-X.Y.Z-arm64.dmg |
| macOS (Intel) | Folio-X.Y.Z.dmg |
| Windows | Folio Setup X.Y.Z.exe (or Folio-X.Y.Z-portable.exe) |
| Linux | Folio-X.Y.Z.AppImage (or folio_X.Y.Z_amd64.deb) |
The desktop app shells out to the host's folio-viewer Python CLI; if
it is missing, the launcher offers an "Open install docs" button. See
docs/methodology/desktop-runtime.md
for the rationale.
Folio Desktop ships unsigned and un-notarized today. Both macOS Gatekeeper and Windows SmartScreen will warn on first launch. This is expected — the workarounds below are safe; signing and notarization are tracked as a release follow-up.
macOS — "Apple は、"Folio" にマルウェアが含まれていないことを検証できませんでした" / "Apple could not verify that "Folio" is free of malware":
# 1. Drag Folio.app into /Applications first.
# 2. Then strip the quarantine attribute Chrome / Safari put there:
xattr -dr com.apple.quarantine /Applications/Folio.app
open /Applications/Folio.appOr, without Terminal: right-click Folio.app in Finder → Open →
confirm in the dialog. After that, normal double-click works.
If macOS shows "Folio was blocked" in System Settings → Privacy & Security, scroll to the bottom and click Open Anyway.
Windows — "Microsoft Defender SmartScreen prevented an unrecognized app from starting":
Click More info → Run anyway. Or use the portable
Folio.X.Y.Z.exe and approve the unverified-publisher prompt.
Linux — .AppImage works without prompts; .deb is unsigned:
chmod +x Folio-X.Y.Z.AppImage
./Folio-X.Y.Z.AppImage
# or for the .deb:
sudo dpkg -i folio-desktop_X.Y.Z_amd64.debVerifying the download — every release ships
SHA256SUMS-{macos-arm64,linux-x64,windows-x64}.txt. Compare locally:
shasum -a 256 Folio-X.Y.Z-arm64.dmg # macOS / Linux
certutil -hashfile "Folio Setup X.Y.Z.exe" SHA256 # WindowsBrowse the Folio docs or build them locally:
cd apps/docs
npm install
npm run dev # → http://127.0.0.1:4321/The site is auto-deployed to GitHub Pages on every push to main that
touches apps/docs/.
A maintainer cuts a release by pushing a tag of the form vX.Y.Z:
make verify # CI gate locally
git tag v0.2.0
git push origin v0.2.0Two workflows then fire:
release-python.ymlbuildsdist/folio_kit-*.whl+dist/folio_kit-*.tar.gz, smoke-tests the wheel in a clean venv, and attaches both plus aSHA256SUMS.txtto a draft GitHub Release.release-desktop.ymlbuildsviewer/dist/, then runselectron-builderon macOS / Windows / Linux runners, attaching DMG, Setup, AppImage, and zip artifacts to the same draft Release.
The release stays in draft until a human flips it to Published.
Full procedure in
docs/methodology/release.md.
This repo follows an AI-first operating model: compact router docs, structured task state, and a single deterministic verification gate.
make agent-init # restart context for the next agent
make verify # harness-check + drift-check + validate-docs
# + pytest + 6 smokes (cli, materialize, scripts,
# mcp, extension-kinds, viewer)See AGENTS.md and
docs/methodology/harness-engineering.md
for the full operating model.