{"id":51133570,"url":"https://github.com/nyuta01/folio","last_synced_at":"2026-06-25T15:01:33.995Z","repository":{"id":357025745,"uuid":"1234807321","full_name":"nyuta01/folio","owner":"nyuta01","description":"Portable, AI-native data sheets.","archived":false,"fork":false,"pushed_at":"2026-05-11T02:20:40.000Z","size":1654,"stargazers_count":0,"open_issues_count":16,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T02:24:53.758Z","etag":null,"topics":["agent-skills","ai-agents","claude","cli","data-contract","data-engineering","duckdb","mcp","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/folio-kit/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nyuta01.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-10T17:04:24.000Z","updated_at":"2026-05-11T02:20:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nyuta01/folio","commit_stats":null,"previous_names":["nyuta01/folio"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/nyuta01/folio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyuta01%2Ffolio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyuta01%2Ffolio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyuta01%2Ffolio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyuta01%2Ffolio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nyuta01","download_url":"https://codeload.github.com/nyuta01/folio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyuta01%2Ffolio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34780126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","claude","cli","data-contract","data-engineering","duckdb","mcp","python"],"created_at":"2026-06-25T15:01:33.058Z","updated_at":"2026-06-25T15:01:33.987Z","avatar_url":"https://github.com/nyuta01.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/nyuta01/folio/main/apps/desktop/build/icon-128.png\" alt=\"Folio\" width=\"96\" height=\"96\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eFolio\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://pypi.org/project/folio-kit/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/folio-kit?label=folio-kit\"\u003e\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/folio-agent-skills\"\u003e\u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/v/folio-agent-skills?label=folio-agent-skills\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/folio-kit/\"\u003e\u003cimg alt=\"Python\" src=\"https://img.shields.io/pypi/pyversions/folio-kit\"\u003e\u003c/a\u003e\n\u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-yellow.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/nyuta01/folio/actions/workflows/verify.yml\"\u003e\u003cimg alt=\"verify\" src=\"https://img.shields.io/github/actions/workflow/status/nyuta01/folio/verify.yml?branch=main\u0026label=verify\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nPortable, AI-native data sheets.\n\nA **sheet** is a directory of plain files that AI agents read and write as\nfirst-class users, that humans review later, and that travel as a `tar`\narchive across machines.\n\n```\nmy-sheet/\n├── contract.yaml         # required — ODCS subset\n├── records.jsonl         # required — one JSON object per line\n├── derivations/          # optional — derivation files\n├── scripts/              # optional — reusable scripts\n├── skills/               # optional — packaged operating procedures\n├── provenance.jsonl      # append-only audit log\n└── README.md             # optional, with typed frontmatter\n```\n\n## Surfaces\n\n- **`folio`** — Python SDK + CLI (init, validate, query, list, count,\n  upsert, delete, materialize, status, provenance, serve, script,\n  skill, export).\n- **`folio-viewer`** — local-only FastAPI + React UI for human review.\n\n## Documentation\n\nUser-facing documentation lives in [`apps/docs/`](apps/docs/) (Astro +\nStarlight). Run it locally:\n\n```bash\ncd apps/docs\nnpm install\nnpm run dev      # → http://127.0.0.1:4321/\n```\n\nOr read the canonical sources directly:\n\n- [Design overview](docs/design-docs/overview.md) — the spec\n- [ADRs](docs/design-docs/adrs/README.md) — architectural decisions\n- [Examples](examples/README.md) — five sheets covering four canonical use cases (customers + its customer-revenue sidecar, research-notes, research-memory, onboarding) — all run offline\n\n## Quickstart\n\n```bash\nuv tool install folio-kit          # → installs the `folio` command\n\nfolio validate examples/customers\nfolio materialize examples/customers --actor agent:demo\nfolio serve examples/customers --port 3000 --actor agent:human\n# → http://127.0.0.1:3000/\n```\n\n## Install\n\nReleases ship three artifact families. Pick the one that matches how you\nwant to use Folio.\n\n### Python (CLI + SDK + Viewer backend)\n\n```bash\n# from PyPI (preferred)\npipx install folio-kit\nuv tool install folio-kit\n\n# from a tagged GitHub Release wheel\npipx install https://github.com/nyuta01/folio/releases/download/vX.Y.Z/folio_kit-X.Y.Z-py3-none-any.whl\n```\n\nThe PyPI distribution name is `folio-kit`; the wheel installs two\nconsole scripts: `folio`, `folio-viewer`. SHA-256\nchecksums for every release artifact are attached as `SHA256SUMS.txt`.\n\n### Folio Desktop (Electron wrapper)\n\nDownload the installer for your platform from the\n[latest release](https://github.com/nyuta01/folio/releases/latest):\n\n| Platform | Asset |\n|---|---|\n| macOS (Apple Silicon) | `Folio-X.Y.Z-arm64.dmg` |\n| macOS (Intel) | `Folio-X.Y.Z.dmg` |\n| Windows | `Folio Setup X.Y.Z.exe` (or `Folio-X.Y.Z-portable.exe`) |\n| Linux | `Folio-X.Y.Z.AppImage` (or `folio_X.Y.Z_amd64.deb`) |\n\nThe desktop app shells out to the host's `folio-viewer` Python CLI; if\nit is missing, the launcher offers an \"Open install docs\" button. See\n[`docs/methodology/desktop-runtime.md`](docs/methodology/desktop-runtime.md)\nfor the rationale.\n\n#### First-launch warning (unsigned builds)\n\nFolio Desktop ships **unsigned and un-notarized** today. Both macOS\nGatekeeper and Windows SmartScreen will warn on first launch. This is\nexpected — the workarounds below are safe; signing and notarization\nare tracked as a release follow-up.\n\n**macOS** — *\"Apple は、\"Folio\" にマルウェアが含まれていないことを検証できませんでした\"* / *\"Apple could not verify that \"Folio\" is free of malware\"*:\n\n```bash\n# 1. Drag Folio.app into /Applications first.\n# 2. Then strip the quarantine attribute Chrome / Safari put there:\nxattr -dr com.apple.quarantine /Applications/Folio.app\nopen /Applications/Folio.app\n```\n\nOr, without Terminal: right-click `Folio.app` in Finder → **Open** →\nconfirm in the dialog. After that, normal double-click works.\n\nIf macOS shows *\"Folio was blocked\"* in **System Settings → Privacy \u0026\nSecurity**, scroll to the bottom and click **Open Anyway**.\n\n**Windows** — *\"Microsoft Defender SmartScreen prevented an\nunrecognized app from starting\"*:\n\nClick **More info** → **Run anyway**. Or use the portable\n`Folio.X.Y.Z.exe` and approve the unverified-publisher prompt.\n\n**Linux** — `.AppImage` works without prompts; `.deb` is unsigned:\n\n```bash\nchmod +x Folio-X.Y.Z.AppImage\n./Folio-X.Y.Z.AppImage\n\n# or for the .deb:\nsudo dpkg -i folio-desktop_X.Y.Z_amd64.deb\n```\n\n**Verifying the download** — every release ships\n`SHA256SUMS-{macos-arm64,linux-x64,windows-x64}.txt`. Compare locally:\n\n```bash\nshasum -a 256 Folio-X.Y.Z-arm64.dmg     # macOS / Linux\ncertutil -hashfile \"Folio Setup X.Y.Z.exe\" SHA256   # Windows\n```\n\n### Documentation site\n\nBrowse [the Folio docs](https://nyuta01.github.io/folio/) or build them\nlocally:\n\n```bash\ncd apps/docs\nnpm install\nnpm run dev      # → http://127.0.0.1:4321/\n```\n\nThe site is auto-deployed to GitHub Pages on every push to `main` that\ntouches `apps/docs/`.\n\n## Releases\n\nA maintainer cuts a release by pushing a tag of the form `vX.Y.Z`:\n\n```bash\nmake verify             # CI gate locally\ngit tag v0.2.0\ngit push origin v0.2.0\n```\n\nTwo workflows then fire:\n\n- **`release-python.yml`** builds `dist/folio_kit-*.whl` + `dist/folio_kit-*.tar.gz`,\n  smoke-tests the wheel in a clean venv, and attaches both plus a\n  `SHA256SUMS.txt` to a draft GitHub Release.\n- **`release-desktop.yml`** builds `viewer/dist/`, then runs\n  `electron-builder` on macOS / Windows / Linux runners, attaching DMG,\n  Setup, AppImage, and zip artifacts to the same draft Release.\n\nThe release stays in **draft** until a human flips it to **Published**.\nFull procedure in\n[`docs/methodology/release.md`](docs/methodology/release.md).\n\n## Repository harness\n\nThis repo follows an AI-first operating model: compact router docs,\nstructured task state, and a single deterministic verification gate.\n\n```bash\nmake agent-init   # restart context for the next agent\nmake verify       # harness-check + drift-check + validate-docs\n                  # + pytest + 6 smokes (cli, materialize, scripts,\n                  #   mcp, extension-kinds, viewer)\n```\n\nSee [`AGENTS.md`](AGENTS.md) and\n[`docs/methodology/harness-engineering.md`](docs/methodology/harness-engineering.md)\nfor the full operating model.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyuta01%2Ffolio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnyuta01%2Ffolio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyuta01%2Ffolio/lists"}