Where it hurts, and why.

The customer meeting on Friday

A sales contract depends on documentation you don't have.

Your account team is pitching to a customer that requires technical datasheets for every component they integrate with. They need: purpose, interfaces, SLAs, dependencies, security classification, ownership. By Friday.

Right now, that information exists — somewhere. A few fragments are in READMEs. Some is in the wiki but out of date. The SLAs were agreed in a Slack thread two quarters ago and never written down formally. The security team has a classification doc for some of your services but not others. The deal stalls while three engineers spend half their week reconstructing what they already know, in a format they've never built before.

We had the information. We just didn't have it together. By the time we assembled the deck, the deal had a red flag against our response time.

With Folio

Every component has a datasheet that was validated at commit time and contains exactly the fields a customer datasheet needs. folio export payment-service produces a typeset PDF from the working source. The "update the deck" step is gone. What your engineers have been maintaining all along is the deck.

The information was always there. Folio makes it present.

The silent deprecation

Something you killed six months ago is still in production.

You announced the deprecation on Slack. You updated the README. You sent an email to the consumers you knew about. You moved on.

Today, a customer report comes in: their integration just broke. They were calling the old service all along. It worked until a dependency rotated and now it doesn't. Your runbook points at a monitoring dashboard that hasn't existed for six months. The person who built the replacement is on vacation. The fix is obvious, but nobody can prove what calls the old service without an afternoon of log-grepping.

We thought we'd communicated the deprecation. We had. Just not to everyone. And there was no way to ask the question "who still depends on this?"

With Folio

Deprecations are structured. A datasheet with lifecycle = "deprecated" is flagged in every folio list, counted in folio stats, and queryable: SELECT ?ds WHERE { ?ds folio:requires ?r . ?r folio:requirementName "old-service" } answers "what still depends on this" in one query. The runbook link integrity fails at folio check-links time, not when a customer reports an outage.

You still have to communicate the deprecation. But now the communication has a receipt.

The new engineer's first question

"What do we own, and who owns it?"

A new hire joined this week. On Tuesday morning they ask you the most reasonable question a new hire can ask: "Can you show me a list of everything the team owns, with who's accountable for each?"

You open four tabs. The wiki has a list, from 2023. The internal service catalog has a different list, incomplete. The repo-of-repos README hasn't been touched since the team reorganized. You realize that nobody actually has the canonical answer — it lives distributed across six people's heads and nobody has written it down in a way that would survive any of those six people leaving.

You spend an hour assembling something approximate. Your new hire reads it and nods. They do not ask any follow-up questions about it, which would be good news if they were reading a reliable document. They're not asking because they already learned, in their first week, that the answers aren't written down and the senior engineers are the source of truth. You have taught them, unintentionally, to interrupt you whenever they need context.

The knowledge was in the team. It was not in the team's artifacts. We had silently made the team not scale.

With Folio

folio list is the answer. Every datasheet, with owner, lifecycle, classification, in a table. folio stats shows the breakdowns: how many services are active, how many are deprecated, who owns what, how stale each one's last review is. The new hire has the canonical list because the canonical list exists. And they can contribute to it on day one — their first PR can be a datasheet for a component they're inheriting, and the validation gate will tell them if they've missed a required section.

Making knowledge survive the team that created it is what documentation is for. Folio is an explicit tool for doing that.

The audit

The compliance team asks which of your services handle confidential data.

Your organization is going through an audit. Security needs a list of every service that processes confidential information, with its owner, current classification, and last-reviewed date. The list will be shown to an external auditor next week.

You don't have this. You have it approximately, spread across architecture diagrams, classification spreadsheets (three different ones, from different eras), Slack pins, and the contents of a few senior engineers' browsers' history. Assembling the actual answer requires about two days of focused work, which Security doesn't have and your team can't spare.

We produced a list. I'm 80% sure it's accurate. That 20% is going to be very loud if the auditor picks a bad service to ask questions about.

With Folio

One query:

folio query 'PREFIX folio: <https://folio.tools/vocab#>
  SELECT ?ds ?owner ?reviewed WHERE {
    ?ds folio:classification "confidential" ;
        folio:owner ?owner ;
        folio:lastReviewed ?reviewed
  } ORDER BY ?reviewed'
ds                    owner              reviewed
----------------      ---------------    ---------------
ds:payment-service    platform-team      2026-03-12
ds:auth-gateway       platform-team      2026-04-01
ds:mission-console    ops-team           2026-04-10

You also get sorted-oldest-first so the auditor's favorite question — "when was this last reviewed?" — has an answer that surfaces stale entries before the auditor does.

The customer inquiry you want to say yes to

"Do you have experience with X?" You probably do. You can't prove it in time.

You run a small shop — a consultancy, an agency, an indie dev with a few past clients. You've built up real IP: reusable components, libraries, starter templates, patterns you've proven out across engagements. It lives in your repositories, in your engineers' heads, and in nobody's formal inventory.

Then an email arrives. A prospect is evaluating vendors. They describe a project that needs three capabilities. You know — you know — that you have most of it already. You've solved two of those three problems for past clients and could stand up the third quickly by extending work you've done before.

But you have 48 hours to respond, and you don't have your own capabilities written down. The inventory is in people's heads. Your senior engineer is on vacation. You could spelunk through five repositories to reconstruct the answer, but by Thursday your response is late and the prospect has already gone with someone else. Or you could send a vague, hedging reply that undersells what you actually have, because confidence in the specifics would require work you can't do in time.

We had the capability. We couldn't demonstrate the capability. From the prospect's perspective those two things are the same.

With Folio

The one-time cost is writing a datasheet per reusable capability — an afternoon, maybe two, for a small portfolio. The payoff is that every future inquiry of this shape becomes a tractable question: folio search finds the capabilities, folio list --filter lifecycle=active confirms what's currently supported, folio export produces a typeset capability sheet you can attach to the response.

A new engineer on your team — even one you hired last week — can answer "what do we have that's relevant to this?" without interrupting anyone. The institutional memory of the shop stops living in people's heads and starts living in a queryable record. You can credibly say yes to work you'd otherwise lose.

This is the scenario we built the quickstart around. If the story rings true, go through that guide — it walks through this exact situation end to end.