Software Component Datasheets
Most of your team's best work is buried in past projects. Folio surfaces it.
Hardware engineers solved this decades ago: every chip ships with a datasheet, so anyone can evaluate it without reading the silicon. Folio brings the same discipline to software components — whether they're already polished libraries, or capability that's still embedded inside a past client project waiting to be extracted.
The Analogy
A familiar format. A new use.
Hardware datasheets describe parts you can order. Folio datasheets describe capability you already have — sometimes as a clean library you can drop into any project, sometimes as code embedded inside a past client engagement that would take a couple of days to extract. Either way, the format is the same: the categories adapt, the discipline doesn't.
The hardware datasheet describes a part you can order. The software datasheet describes capability you already possess — in this case, JWT authentication code that exists in three past projects, with a documented two-to-three day path to consolidation. The format is familiar. The discipline is the same. What changes is what counts as a "part."
Who this is for
Teams whose IP outruns their inventory.
Every working team has more capability than it has cataloged. A consultancy with five years of past projects has dozens of patterns, components, and clean implementations buried inside engagements no one looks at anymore. Folio exists to surface them. The biggest payoff isn't for teams whose code is already perfectly modular — it's for the rest of us, who have great work scattered across messy project trees.
Bid the right amount.
When a customer asks "have you done X?" the honest answer is usually "yes, but it's embedded in OldClient-2023." Folio names that capability, scores its extraction effort, and lets you respond with a credible estimate instead of a hedge or an over-promise.
Stop solving the same problem twice.
The third time someone reimplements JWT auth or the same retry pattern, you didn't fail to write a library — you failed to make the existing implementations findable. A datasheet for the pattern, citing where it lives, makes the next discovery a one-command search.
Read it like a chip.
Drop into a portfolio you didn't build and orient yourself the way you'd evaluate a new MCU: identity, interfaces, performance envelope, lifecycle, current form. No spelunking through code. No interrupting people who already moved on.
Three front doors
How do you want to start?
Three guides for three perspectives. Each is self-contained; pick the one that matches what you're trying to do today.
Quickstart
A twenty-minute, story-driven walkthrough. You'll build a small portfolio, then watch Folio turn it into answerable questions — the kind a customer or a new hire would ask. Zero jargon; teaches the mental model with ordinary words.
Tutorial
The technical follow-along. Goes through every core command in order with realistic examples, and covers the advanced features too: SPARQL queries, semantic merge, Rhai migrations, CI integration. For readers who want the full capability surface.
Reading a portfolio
Walks through Folio from the perspective of someone with a hardware/firmware background dropped into a software portfolio. Uses the chip-datasheet analogy throughout. Shows how to evaluate components without reading code.
What the tool does
Six capabilities. One mental model.
A datasheet is a folder with a manifest and some prose. A repository contains datasheets. Everything else is consequence — and it's the consequences that make Folio worth using.
List and filter
See every project in your portfolio with one command. Filter by owner, by lifecycle, by classification, or by any other field. The command you run first, every morning.
Full-text search
BM25-ranked search across every manifest and every section of prose. When a customer says "do you have anything that handles authentication?" the answer is one command away.
Structural queries
For power users: every datasheet becomes RDF triples you can query with SPARQL. "Which confidential services in production depend on deprecated libraries?" is one query, instantly answered.
Typeset PDF export
Generate a polished PDF from any datasheet. Attach it to a customer response or drop it in a board packet. No "update the deck" step — the source your engineers maintain is the source the PDF comes from.
Integrity checks
Every URL gets an HTTP check. Every manifest gets structural validation. Every datasheet's required sections are enforced. Runs in CI. Catches the runbook link that's been broken for six months.
Semantic merge
When two engineers edit in parallel, Folio merges with awareness of TOML and Markdown structure. Non-overlapping additions aren't conflicts. Real disagreements are grouped by shape so you resolve ten related conflicts with one decision.
How we built it
Five commitments, non-negotiable.
Plain text, standard formats.
TOML for structured data, Markdown for prose. Every file is readable by humans, grep, and every editor on the planet. No binary formats. No database. Your repository in ten years will open in an editor that doesn't exist yet.
Git is the transport.
Versioning, history, diffing, blame, bisect, hooks, remotes. We don't reinvent any of it. folio checkpoint is git commit with a validation gate. folio sync is a three-way merge on top of git merge-base.
Local-first, no phone home.
Everything runs on your machine against your local working tree. No cloud. No account. No API key. No analytics. No update check. Folio will never make a network request you did not ask for, ever.
Validation, not prescription.
Folio validates required structure. It does not prescribe prose style, section length, or how you write. Write badly and the tool will still work. The discipline is structural, not stylistic.
Every output is machine-readable.
Every command that prints text has a --json flag. Every error has an exit code. Every script you'd want to write against Folio output can be written. If you can read it, you can pipe it.
Where it fits
Not a wiki replacement. Not a notes app.
Folio lives in the specific space where structured software documentation needs to be authoritative, version-controlled, and queryable. Other tools exist for other needs. Here's how they compare.
| Folio | Confluence / Notion | Obsidian | README.md | |
|---|---|---|---|---|
| Structured schema | yes | no | partial | no |
| Git-native | yes | no | opt-in | yes |
| SPARQL queryable | yes | no | no | no |
| Semantic merge | yes | n/a | no | no |
| PDF export | yes | yes | plugin | no |
| Runs offline | yes | partial | yes | yes |
| Phone home | no | yes | self-host | no |
| License cost | $0 | $ | $ | $0 |
Start
Twenty minutes. No long commitment.
Pick the front door that matches your goal. Build a small portfolio, exercise the tool, see whether the discipline pays off for the kind of work you do. The whole loop fits in an afternoon.