Quickstart · 20 minutes
The customer inquiry.
It's Tuesday afternoon. A prospect sends an email asking if you have experience with a capability they need. The honest answer is "yes, sort of — it's buried in three past projects, each slightly different." In the next twenty minutes, you're going to build a small Folio portfolio of your latent capability, then use it to write a response that wins the engagement on your actual strengths.
Hi —
We're evaluating vendors for a customer-facing portal we're building. We need user authentication (SSO through our existing identity provider), the ability to generate branded PDF statements on demand, and a multi-step customer onboarding flow with save-and-resume. Timeline is tight: we'd like to demo to our board in six weeks.
Can you send over a brief summary of your team's relevant experience in these areas? We're trying to narrow the vendor list to three by Friday.
Thanks,
Priya
A week ago, answering this would have been a meeting. "Dan, didn't we build JWT auth for NorthwindCRM? Kate, weren't you the one who did that PDF report thing for FinanceConsole? What about onboarding — anyone remember?" Then an afternoon of digging through old repos to confirm what's actually there.
By the end of this quickstart, you'll have a Folio portfolio that lets you answer Priya with confidence and specificity. Not "yes we can do that" (which every vendor will say) but "yes; here's what we already have, here's what extraction would cost, here's our estimate."
Create the portfolio.
A Folio portfolio is just a directory with a bit of structure inside. You'll initialize it the same way you'd start any project:
mkdir shop-portfolio && cd shop-portfolio folio init --tier controlled . ok: initialized Folio repository at . tier: Controlled
That's it. You now have a Folio portfolio. It's also a regular git repository, so every future change will be trackable by normal tools.
--tier controlled flag sets how conservative the repo is about what it will accept. Controlled allows up to confidential classification, which is about right for internal consulting work. Other tiers are open (internal only) and restricted (up to restricted).Scaffold four datasheets.
These are the four pieces of capability your shop has built that are relevant to Priya's three asks. The shape of each is different: one is a clean library, one is a capability embedded across three past projects, one is a pattern solved twice in firmware, and one is a prototype built for a single client that never got productionized.
folio new report-generator --owner platform-team folio new jwt-auth-pattern --owner platform-team folio new rs485-framing --owner embedded-team folio new customer-onboarding-flow --owner web-team
Each folio new creates a folder under datasheets/ with a manifest file and section stubs waiting for prose:
ls datasheets/jwt-auth-pattern folio.toml public/ teaser.toml teaser.md sections/ snapshot.md purpose.md interfaces.md non-functional.md dependencies.md revision-history.md
The four you just created cover the four corners of latent-IP space: polished library (report-generator), embedded across projects (jwt-auth-pattern), pattern without a library yet (rs485-framing), and prototype stuck in one client's codebase (customer-onboarding-flow). Between them, they exercise every dimension Folio tracks.
Fill in the state section.
The new thing Folio gives you — the reason the rest of this exercise matters — is the [state] section of the manifest. This is where you describe what form the capability currently takes, where it lives, and what extraction would cost. Open datasheets/jwt-auth-pattern/folio.toml in your editor and add:
[state]
form = "embedded"
extraction_effort = "days"
license_posture = "ours"
last_touched = "2024-08-15T00:00:00Z"
[[state.locations]]
project = "NorthwindCRM"
path = "auth/*"
notes = "Primary implementation. Most polished. Has MFA path."
[[state.locations]]
project = "MetricsPortal-2023"
path = "internal/jwt/"
notes = "Modified copy with simpler refresh logic."
[[state.locations]]
project = "AcmeBilling"
path = "lib/jwt_session.py"
notes = "Earliest version. HS256 only."
What these fields mean, in the words you'd use to explain them to a colleague:
form = "embedded"— the code exists, but buried in past project trees; not a standalone library yet.extraction_effort = "days"— rough estimate of how long it would take to pull this out into something reusable. One of: none, hours, days, weeks, or rebuild (would have to start over from what we learned).license_posture = "ours"— we own this outright. Other options are client-nda, mixed, and third-party.[[state.locations]]— where in your codebase this thing currently lives. You can have as many as you need. Notes are free-form.
Now do the same for the other three datasheets. The values you'll use:
# report-generator: already a clean library
form = "library"
extraction_effort = "none"
license_posture = "ours"
last_touched = "2026-03-22T00:00:00Z"
# (no [[state.locations]] needed for a library)
# rs485-framing: pattern with reference implementations, no library yet
form = "pattern"
extraction_effort = "weeks"
license_posture = "ours"
last_touched = "2024-04-02T00:00:00Z"
[[state.locations]]
project = "AcmeTelemetry-fw"
path = "drivers/comm/rs485.c"
[[state.locations]]
project = "BlueRiverSCADA"
path = "src/io/rs485_link.c"
# customer-onboarding-flow: prototype in one client project
form = "prototype"
extraction_effort = "weeks"
license_posture = "mixed"
last_touched = "2025-12-08T00:00:00Z"
[[state.locations]]
project = "NorthwindCRM"
path = "frontend/onboarding/*"
Four datasheets. Four different states. Each honest about what it is.
Validate and see the portfolio.
Check that all four datasheets pass schema validation:
folio validate ok customer-onboarding-flow ok jwt-auth-pattern ok report-generator ok rs485-framing 4 datasheets: 4 valid, 0 invalid
Then list them as a portfolio at a glance:
folio list ID NAME LIFECYCLE MATURITY OWNER ------------------------- ------------------------- --------------- --------- --------------- customer-onboarding-flow Customer Onboarding Flow in-development beta web-team jwt-auth-pattern JWT Auth Pattern active hardened platform-team report-generator Report Generator active hardened platform-team rs485-framing RS-485 Framing with ... active stable embedded-team 4 datasheets
That's the portfolio. Four capabilities your shop owns, in wildly different states of readiness, all now queryable as a single corpus.
Ask Folio what's ready today.
Priya's email has three asks: SSO/auth, PDF report generation, and multi-step onboarding. You need to know, for each, whether you're starting from zero, starting from a library, or starting from something in between.
folio show report-generator | head ============================================================ Report Generator report-generator v1.4.2 ============================================================ Status: active / hardened Last reviewed: 2026-04-08 Owner: platform-team Classification: internal State: library (ready today) License posture: ours Last touched: 2026-03-22
There it is: library (ready today). For Priya's PDF-report ask, you're not building anything — you're deploying something that works. That's your strongest answer.
folio show jwt-auth-pattern | head ============================================================ JWT Auth Pattern jwt-auth-pattern v0.0.0 ============================================================ Status: active / hardened Last reviewed: 2026-04-12 Owner: platform-team Classification: internal State: embedded (extraction: days) License posture: ours Last touched: 2024-08-15 Lives in: 3 locations: NorthwindCRM, MetricsPortal-2023, AcmeBilling
For auth: embedded (extraction: days). Three implementations exist across past projects; 2-3 days of consolidation work would turn them into a library you could deploy cleanly. That's an honest answer to give Priya, and it's more honest than either "yes we have this" (which hides the extraction cost) or "we'll need to build it" (which undersells real experience).
folio show customer-onboarding-flow | head ============================================================ Customer Onboarding Flow customer-onboarding-flow v0.0.0 ============================================================ Status: in-development / beta State: prototype (extraction: weeks) License posture: mixed Last touched: 2025-12-08 Lives in: 1 location (NorthwindCRM)
For onboarding: prototype (extraction: weeks) and license posture: mixed. There's a working implementation in one past project, but it's coupled to that project's compliance schema. Decoupling it would take a week or two of focused work. You may or may not want to offer to do that for Priya — but now you can say why.
Respond to Priya.
Now you can write the email. Not the generic "we have extensive experience" boilerplate that every vendor sends. A response that is credible because it is specific:
Hi Priya,
Thanks for the RFP. Quick summary of where we stand on your three asks:
PDF statement generation. We have a Typst-based report generator in active use across four client deployments (most recent release 1.4.2). Drop-in ready; we'd plug it into your data model and customize templates. Timeline impact: minimal.
SSO / JWT auth. We've built JWT auth with session management three times, each for a specific customer's identity provider, including a variant with TOTP-based MFA. We would spend the first 2-3 days of the engagement consolidating those implementations into a clean library version for your stack. That gets you a production-ready auth layer by end of week one with no surprises in week three.
Multi-step onboarding with save/resume. We have a working implementation of this pattern from a past engagement, currently coupled to that customer's compliance schema. Decoupling it for reuse is about a week of work. Depending on your compliance requirements, the right answer is probably to quote that decoupling work as part of this engagement and use the outcome on your project.
Happy to walk through any of this in detail. Our team lead is available Thursday or Friday afternoon.
Best,
You
Everything in that email is grounded in something you can point at in your portfolio. If Priya asks for more detail, you run folio show jwt-auth-pattern and read the answer off the screen. If her CTO asks to see something concrete, you run folio export jwt-auth-pattern and hand them a PDF with the same data.
Commit and move on.
Check the portfolio into version control so it's durable:
folio checkpoint "seed portfolio: 4 capability datasheets" ok: committed 17f1342a95 seed portfolio: 4 capability datasheets
The portfolio now lives as a versioned git repository that your whole team can contribute to. Adding the next capability is the same flow: folio new, fill in the manifest, write the prose, validate, commit. Five minutes per component for the common case.
What changed
You have visibility you didn't have Tuesday morning.
Before Folio, your response to Priya would have been a hedge. Either overpromise and sweat the delivery, or underpromise and lose the engagement. Now you can do something different: match specific, stated capability to specific, stated need, with honest extraction estimates for the gaps.
The work you did today — four datasheets, maybe two hours of writing — is permanent. The next time a customer inquiry arrives touching auth or reporting or onboarding, you start already ahead. The time after that, even further ahead. You are no longer rediscovering your own IP every time someone asks about it.
From here
Where to go next.
- Build on this portfolio. Add datasheets for other capability your team has. Each one takes five minutes of scaffolding plus an hour of honest prose.
- Read the technical tutorial. The tutorial goes deep on every Folio command, including SPARQL queries, semantic merge, PDF export, and CI integration.
- Explore from a systems-engineer perspective. The sysengr guide walks through using Folio to read a portfolio someone else built — a skill for new engineers, auditors, and technical leaders arriving on a team.
- See the scenarios. The why page walks through five concrete situations where this discipline changes the picture.