Tygart Media

Blog

  • AI Raises the Floor, Not the Ceiling: A Restoration Industry Commentary on the Real AI Story

    AI Raises the Floor, Not the Ceiling: A Restoration Industry Commentary on the Real AI Story

    AI is raising the floor of the restoration industry. It is not raising the ceiling. The ceiling will always belong to the operators who have actually stood in a flooded basement at 2 a.m. and made the call. Once you internalize that distinction, the panic about AI replacing skilled trades collapses, and a more useful question takes its place: what happens to an industry when the floor finally catches up to the people who have been carrying it?

    This is a commentary about restoration. It is also a commentary about AI in general. The two stories are the same story.

    The Floor and the Ceiling

    Every industry has a floor and a ceiling. The floor is the minimum competence a customer can expect from anyone in the trade. The ceiling is what the best practitioners are capable of — the judgment calls, the pattern recognition, the gut feel that comes from doing the work for fifteen years and seeing every kind of failure mode at least twice.

    In restoration, the floor has been embarrassingly low for a long time. There are operators in this industry who genuinely should not be allowed near a moisture meter. They mis-scope projects, they bill for equipment they did not run, they cut corners on containment, and they sell jobs they cannot deliver. They depress the curve for everyone who is trying to do this work properly. Every honest contractor who has ever lost a job to a lowball bid from a fly-by-night competitor knows exactly who I am talking about.

    The ceiling, meanwhile, lives inside the heads of people who have been at this for decades. The Project Manager who can walk into a loss and tell you within ten minutes which insurance adjuster will push back, which trades need to be sequenced first, and which homeowner is going to file a complaint regardless of the outcome. The technician who knows by smell alone whether the mold is active or dormant. The estimator who has internalized the regional cost variance between a Houston hurricane and a Minneapolis ice dam and can write an accurate scope without opening Xactimate. None of that knowledge lives in a database. It lives in the brains of the operators who built it the hard way.

    What AI Actually Does to Skilled Trades

    Here is the part most takes get wrong. AI is not coming for the ceiling. AI is coming for the floor.

    What AI does extremely well is the work that is procedural, well-documented, and pattern-matched against existing data. Writing the initial scope of work. Generating a clean estimate from a photo set. Drafting customer communications. Filling in the IICRC-aligned drying log. Producing the daily progress report. Pulling the right documentation for the carrier. Comparing this loss against the last hundred similar losses in the database and flagging the parts that look off.

    None of that is the hard part of restoration. The hard part of restoration is the judgment that comes after the data is collected. The hard part is knowing that the moisture reading the AI just generated is technically correct but practically wrong because of the building envelope quirk you cannot see from the photo. The hard part is reading the homeowner across the kitchen table and knowing they need to hear the truth a specific way or they will fire you by Thursday. The hard part is the call between mitigation and replacement when the numbers are genuinely close and the carrier is going to fight you either way.

    AI raises the floor by making the procedural part faster, cheaper, and more consistent across the industry. The technician who used to spend two hours writing a sloppy scope now has a clean scope in fifteen minutes. The estimator who used to fight Xactimate now has a draft to react to. The office admin who used to chase signatures now has a workflow that runs itself. All of that is the floor rising.

    The ceiling — the actual judgment, the actual experience, the actual feel for the work — is unmoved. It is still entirely inside the heads of the operators who built it. If anything, it becomes more valuable because the floor is rising fast enough that the only meaningful differentiation left is what the AI cannot replicate.

    Why the Bad Actors Get Starved Out

    This is the part that should make every honest operator in the restoration industry hopeful rather than nervous.

    The rogue restoration company that has been distorting the curve for fifteen years survives on a specific edge. They can underbid the honest operators because they cut corners on the procedural work — they do not document properly, they do not run the right equipment, they do not follow IICRC standards, they do not handle the carrier paperwork with any rigor. The bid they hand a homeowner looks competitive only because the work they are quoting is not the same work an honest contractor would quote.

    When AI raises the floor, that arbitrage disappears. The procedural work becomes table stakes. Any contractor with a smartphone can now produce a clean scope, a defensible drying log, a proper carrier-facing report. The reckless contractor who used to win on speed-by-cutting-corners is suddenly competing on a level surface against operators who have always done the work properly and now have AI making them faster too.

    What the reckless contractor cannot do is the ceiling work. They cannot reproduce the judgment, because they never had it. They cannot reproduce the relationships with adjusters, the reputational depth, the operator instinct. When the floor rises and the differentiation moves up to the ceiling, the bad actors are the first ones starved out. Their entire edge was the floor being low.

    This is the part nobody is telling honest restoration operators clearly enough. AI is not your threat. AI is the thing that finally levels the playing field against the contractors who have been undercutting you on quality for years.

    Data Is Cheap, Fast, and Incomplete

    Right now, in 2026, data is cheap. Compute is cheap. Inference is cheap. Every AI system on the market is leveraging the same approximate pool of public data, the same scraped industry documentation, the same generic training corpus. That is why the AI-generated restoration content flooding the internet right now is so painfully shallow — it can describe what a Category 3 water loss looks like in textbook terms, but it cannot tell you what it actually feels like to walk into one.

    The data is incomplete. It will stay incomplete until somebody systematically extracts the tacit knowledge from the operators who actually have it. That is the part of the AI story almost everybody is missing. The models are not bottlenecked on compute. They are bottlenecked on the kind of experiential, hard-won, in-the-field knowledge that has never been written down and never made it into the training corpus.

    This is true across every industry, not just restoration. It is true in HVAC, in commercial real estate, in healthcare operations, in B2B sales, in any field where the floor is procedural and the ceiling is experiential. The AI floor will continue to rise everywhere. The ceiling will continue to belong to the people who actually did the work.

    The Human Distillery

    This is why the most important AI work happening right now is not building bigger models. It is what we are calling the Human Distillery — the deliberate, structured extraction of tacit knowledge from industry insiders, captured in a form that becomes AI-ready and operator-ready at the same time.

    The way you do this is not with a survey. It is not with a content brief. It is with a long conversation with somebody who has spent twenty years in the field, asking them the questions only an insider would know to ask, then converting their answers into structured artifacts that capture the judgment patterns underneath the words. The scope decisions they make instinctively. The risk signals they read before anyone else sees them. The customer-handling moves they have refined across thousands of jobs. The mistakes they made early in their career and the corrections they internalized.

    That body of knowledge has historically died with the operator who held it. They retire, they sell the business, the kid takes over without the same instincts, and the depth of the operation drops a tier. The industry loses that ceiling-raising knowledge every time a senior operator walks away.

    The Human Distillery is the methodology for stopping that loss. For a direct take on what this moment means specifically for senior operators, see this letter to the older generation of operators in the AI era. You distill the knowledge while the operator is still in the field, you convert it into both AI-ready training data and operator-ready playbooks, and you compound it. The first restoration company that does this systematically will have a competitive moat that no AI system can replicate by ingesting public data, because the knowledge you are encoding was never public in the first place.

    What This Looks Like in Practice

    Imagine a regional restoration operator with thirty years of field experience. Imagine sitting down with that operator for ten hours across a series of structured conversations. Imagine asking them to walk through every category of loss they have ever handled — water, fire, mold, storm, biohazard, commercial, residential, multi-unit — and surface the specific judgment moves they make at each decision point.

    What scope are they running for a Cat 3 with mixed materials in a 1980s slab-on-grade? What changes if the homeowner is elderly and lives alone? What changes if the adjuster is from a specific carrier they have history with? What changes if the loss happened on a Thursday before a holiday weekend?

    None of that is in any database. None of it is in any IICRC standard. It is the ceiling. It is the thing that makes that operator’s company twice as profitable as the regional competitor down the road who has the same trucks and the same equipment and the same certifications.

    The Human Distillery captures it. It becomes a structured artifact the operator can use to train their own next generation of technicians. It becomes AI-ready content that the operator’s own AI tooling can use to outperform every generic restoration-trained model on the market. And critically, it stays inside the operator’s company. It is not training data for the broader model pool. It is the operator’s proprietary ceiling, made durable and transferable.

    Why This Should Give the Industry Faith

    The anxiety about AI in restoration — and in every skilled trade — comes from a flawed mental model. The model says: AI gets better, humans get less valuable, eventually AI does the job. That model is wrong.

    The correct model is: AI raises the floor faster than humans can lower it, so the floor rises. The procedural work that used to differentiate okay operators from bad operators becomes commoditized. The bad operators, who were surviving by underdelivering on the floor, get starved out because the floor is now too high for them to fake. The honest operators get faster and more profitable because their procedural work is now AI-accelerated. And the great operators, the ones with the ceiling-level experience, become the most valuable people in the industry, because the only remaining differentiation is the part AI cannot do.

    That is not a future to fear. That is a future where the people who have always been doing this work properly finally get to compete on the merits.

    The very best of who we are as an industry is about to open up. The contractors who have been holding the line on quality for decades — paying their technicians properly, running their equipment to spec, documenting their work the right way, treating their customers like neighbors — are about to find out that the playing field is finally tilting in their direction. The race to the bottom is ending. The race to the top is starting.

    Have faith. The knowledge will be the value again. It always was. It is just becoming visible again, because the noise is finally getting filtered out.

    Frequently Asked Questions

    Is AI going to replace restoration contractors?

    No. AI is replacing the procedural and documentation work that used to consume hours of a contractor’s day — scoping, estimating, drying logs, carrier paperwork. The judgment work that defines a great restoration operator (reading a loss site, sequencing trades, handling adjusters, managing homeowner expectations) is unchanged and arguably more valuable, because it is now the only meaningful differentiator left.

    What does “AI raises the floor, not the ceiling” actually mean?

    The floor is the minimum competence a customer can expect from any operator in the industry. The ceiling is what the best operators are capable of. AI commoditizes the procedural work, which lifts the minimum baseline across the industry. It does not touch the experiential judgment that defines the top performers. The gap between average and excellent does not close. The gap between bad and average disappears.

    Why will bad actors get pushed out of the restoration industry?

    Bad actors survive on an arbitrage where they underbid honest contractors by cutting corners on procedural work — documentation, equipment, IICRC standards, carrier-facing reports. When AI makes that procedural work fast and cheap for everyone, the underbidding edge disappears. Honest operators get the same speed advantage without sacrificing quality. The bad actors are left competing on judgment and experience, which they never had to begin with.

    What is the Human Distillery?

    The Human Distillery is a structured methodology for extracting tacit, hard-won industry knowledge from experienced operators and converting it into AI-ready and operator-ready artifacts. It captures the judgment patterns, decision frameworks, and field instincts that have historically lived only inside the heads of senior practitioners and disappeared when those people retired. It is how a restoration company turns its founder’s thirty years of experience into a durable competitive asset.

    If AI training data is incomplete, why is AI still useful in restoration today?

    AI is useful today for the procedural floor work — scoping, documentation, customer communication, report generation — because those tasks are pattern-matched against public, well-documented content. The incompleteness shows up the moment you ask AI to make a judgment call that requires tacit field experience. Used inside its actual capability envelope, AI is a force multiplier for any honest operator. Used outside that envelope, it produces the shallow, generic content the industry is currently drowning in.

    How should a restoration company prepare for the AI shift?

    Two parallel moves. First, deploy AI aggressively on the procedural floor — scoping, estimating, documentation, customer-facing communication — to capture the speed and margin advantages. Second, systematically extract the tacit knowledge inside the company’s senior operators using a Human Distillery methodology, and build a proprietary knowledge layer that becomes the company’s defensible ceiling. The companies that only do the first move will be commoditized. The companies that do both will dominate their regions.

    The Bottom Line

    The restoration industry is a perfect commentary on AI in general. Fancy tools and faster calculations are not the gold. The gold, which it always has been, is the learned experience. AI is raising the floor, and the floor needed to be raised. The rogue contractors will be starved out. The reckless ones will go away. The honest operators with real experience will find themselves on a playing field that finally rewards what they have always been doing properly. And the ceiling will keep belonging to the people who actually showed up, did the work, and earned the knowledge the hard way.

    That is when the knowledge will be the value again, just like it always was. The ceiling will start to rise. The very best of who we are as an industry will open up opportunities for the people who built it. Have faith. The floor was the part that was broken. The floor is finally getting fixed.

    The Tacit Knowledge Cluster — Further Reading

    This piece is part of a larger body of writing on what the AI shift and the broader software-platform shift actually mean for service professions and the workers in them. The full cluster:

    The Core Thesis

    For Your Career

    Service Profession Playbooks

    Industry-Specific Trade Answers

    Direct Letters to Each Audience

    For Practitioners

  • Restoration Company Multi-Location Expansion: When to Open a Second Market (2026)

    Restoration Company Multi-Location Expansion: When to Open a Second Market (2026)

    Every restoration owner who clears $5M in annual revenue eventually faces the same fork in the road: dominate the home market harder, or plant a flag in a second city. The wrong answer is not financially fatal — but it usually adds two or three years of expensive learning before the business starts compounding again. With private equity platforms now operating in 30+ states and the industry consolidating from roughly 15,000 firms toward fewer than 10,000 by 2030, that learning window is closing.

    This is the operator-level decision underneath the M&A headlines. Here is the honest framework for it.

    The PE backdrop you are competing against

    Before deciding whether to open a second location, understand what the buyers up the food chain are doing. Reported industry coverage in 2025 and 2026 shows over $6 billion has been deployed across roughly 50+ restoration platforms since 2018, with quality operators trading in the 4x–7x EBITDA range. Fortify Companies — backed by Osceola Capital — combined Rytech Restoration and Insurcomm to serve more than 100 markets across 30+ states. LP First Capital launched Rewind Restoration with an explicit “partner with local leaders, then scale via acquisitions” thesis. Morgan Stanley Capital Partners acquired American Restoration, which operates across approximately 10 states through eight regional brands.

    The pattern is the same in every deal: platforms are not opening locations. They are buying them. A platform spends 18 months building infrastructure, then acquires a $3M–$5M regional operator and bolts it on at a roughly 5x EBITDA multiple. If you are an owner expanding organically into a new market the slow way, you are competing for the same techs, the same referral relationships, and the same carrier slots against a buyer with cheaper capital and a centralized back office.

    That does not mean organic expansion is wrong. It does mean you need to be honest about why you are doing it and what the finish line looks like.

    The four real reasons owners open a second location (only two are good)

    In conversations across the industry, the rationales for a second location tend to cluster into four categories. Two of them tend to work. Two of them tend to bleed cash.

    1. The carrier asked for it. Strong reason. If you are on a Contractor Connection, Alacrity, or Code Blue program and your performance metrics in market A have earned you a request to cover market B, the demand is already there before you sign the lease. The carrier is effectively pre-funding your CAC. This is the cleanest second-location case in restoration.

    2. A key employee will leave if they do not get equity in something they can run. Reasonable reason. Promoting your best operations manager into a second-market GM role with a real P&L and a real equity slice is often cheaper than losing them to a competitor. The risk is that you are choosing the market for HR reasons, not market reasons. Mitigate it by making the GM put together a real go-to-market plan before you commit capital.

    3. The home market feels “tapped out.” Usually wrong. Industry coverage of restoration economics in 2026 — including reporting from Push Leads and Paul Davis — repeatedly notes that most owners who feel tapped out have actually capped their CAC channels, not their market. A second location does not solve a Google Ads ceiling, an LSA neglect problem, or a referral program that has gone stale. It just spreads the same problem over two cities.

    4. “It will be worth more at exit.” Almost always wrong on its own. Multi-location restoration platforms do command higher multiples, but the premium comes from diversified revenue and demonstrated systems — not from the existence of a second address. A second location that loses money for three years actively destroys exit value because it drags EBITDA and signals that the operator cannot run multi-site.

    The financial test before you sign the lease

    The math is unforgiving. Restoration industry reporting on unit economics generally points at the same benchmarks: water mitigation gross margins in the high 40s to mid 50s, blended company gross margins of roughly 38–45%, and net margins for healthy operators in the 8–15% range. Channel CAC tends to run roughly $100–$180 per acquired job on well-optimized Google Ads, $200–$400 on poorly run campaigns, and effectively the lowest CAC on agent and adjuster referrals.

    Run this test before committing:

    • Home market net margin must be at least 10% on a trailing-twelve-month basis. If it is not, you do not have a scalable model yet. Fix the unit economics in market A before duplicating them in market B.
    • You must have at least 6 months of fully loaded operating cash for the new market. A new market typically does not break even on operating cash for 12–18 months. Most “failed” second locations actually ran out of patience before they ran out of demand.
    • CAC in the new market should be modeled at 2x your home-market CAC for the first year. No agent relationships, no adjuster history, no organic search ranking. Plan for it, do not be surprised by it.
    • You must have a designated GM willing to live in the new market. Owner-commuter second locations have a documented bad track record across the industry. The job is too relationship-driven for absentee leadership.

    What the structure should look like in year one

    The second-location org chart that tends to survive is lean and asymmetric. The home market keeps centralized accounting, marketing, estimating support, and Xactimate review. The new market gets a GM, two to three production crews, one project manager, and a dedicated office coordinator. Sales and BD belong to the GM full time — this is non-negotiable because nothing else recovers if local referral relationships are not being built.

    Approximate revenue target in year one for a single new market: $1.2M–$2.0M, with a planned net loss in the first 6–9 months and a target of break-even monthly run-rate by month 12. If you cross break-even faster, the carrier-pre-funded scenario was real. If you are still bleeding past month 18, the most common honest answer is that the market choice was wrong — not that the team needs more time.

    Single-market dominance: the underrated alternative

    For a meaningful share of $3M–$8M restoration operators, the highest-return move is not a second location at all. It is doubling down on the existing market with a vertical-line expansion — adding contents cleaning, mold remediation, or reconstruction in-house — and grinding the home metro toward 6–10% market share.

    The math favors this more often than owners assume. A second service line in an existing market shares overhead, shares referral relationships, and adds revenue at a lower marginal CAC than any new geography can. A $5M single-market shop with diversified service lines and clean books frequently exits at a higher multiple than a $7M two-market shop with one money-losing location, because buyers price systems and predictability, not address count.

    The exit-aware framing

    If your 5-year plan is to sell to a PE platform or a strategic buyer, the question is not “how many locations do I have.” The question is “how cleanly does my next location bolt onto a buyer’s system.” That means:

    • Standard chart of accounts across locations from day one
    • One CRM and one estimating workflow across all sites
    • Documented SOPs for water, fire, mold, contents, and reconstruction
    • Carrier program enrollment at the parent entity level, not the location level
    • GMs on real comp plans with documented KPI scorecards

    If you cannot do those five things in your current single location, you are not ready for a second one. Buyers can tell within a single diligence meeting.

    The bottom line

    A second location is the right move when a carrier is pulling you into a new market, when you would otherwise lose a key operator, and when your home-market unit economics already produce 10%+ net margins and 6+ months of operating runway. It is the wrong move when it is a substitute for fixing CAC, when you are betting on multiple expansion alone, or when the GM does not actually live in the new city. Most owners would create more enterprise value by adding a service line in their existing market than by adding a city.

    The window matters. With platforms still buying regional operators at reported 4x–7x EBITDA multiples and the operator base aging into exit-readiness, the next 3–5 years is the time to either build a defensible multi-market platform or to be the kind of clean, single-market operator that those platforms want to acquire. Both are good outcomes. The bad outcome is being stuck in the middle — two locations, neither profitable, three years older.

    Frequently Asked Questions

    When should a restoration company open a second location?

    When home-market net margins exceed 10% on a trailing-twelve-month basis, when you have 6+ months of fully loaded operating cash to fund the new market, and when either a carrier is requesting expansion or a key operator needs an equity-and-P&L opportunity to retain. Opening a second location to escape a CAC ceiling or to chase a higher exit multiple alone is generally a money-losing decision.

    How long does a second restoration location take to break even?

    Industry experience suggests 12–18 months to monthly operating break-even is normal for a new restoration market without a carrier program pre-funding the launch. With an active carrier program request, the timeline can compress materially. Owners should plan for a net loss in months 1–9 and budget cash accordingly.

    Is it better to add service lines or open a second location?

    For most restoration operators in the $3M–$8M range, adding service lines in the existing market — contents, mold, reconstruction — produces a higher marginal return on capital than geographic expansion, because overhead and referral relationships are already paid for. Geographic expansion makes more sense once a single market is diversified across service lines and approaching 6–10% local share.

    What multiple do multi-location restoration companies sell for?

    Industry reporting in 2026 generally cites a range of approximately 4x–7x EBITDA for quality restoration operators with diversified service lines, with sub-$2M shops trading closer to 2.8x–3.0x SDE. Location count alone does not drive the premium; diversified revenue, documented systems, clean financials, and demonstrated GM-led management at each site are what move the multiple.

    📖 Recommended Reading in Restoration Intelligence

  • How to Rank in Perplexity: The Practitioner’s Implementation Guide (2026)

    How to Rank in Perplexity: The Practitioner’s Implementation Guide (2026)

    Perplexity does not “rank” pages the way Google does. It synthesizes an answer and then chooses which sources to attach to it. That distinction is the entire optimization problem. If your page cannot be cleanly extracted into a short, entity-clear passage, it will not be cited — no matter how strong its backlink profile is.

    This guide is for SEOs and content directors who already know traditional on-page work and want the implementation layer Perplexity rewards. Skip the strategy posts. Here is what to change in the page itself.

    The Three Things Perplexity Is Actually Doing

    When a user submits a query, Perplexity runs three operations in sequence:

    1. Retrieval. Sonar (Perplexity’s underlying search system) pulls a candidate set of URLs from its index using hybrid semantic + keyword retrieval.
    2. Extraction. It reads a bounded chunk of each candidate page. The Sonar API exposes this directly — max_tokens_per_page defaults to 4,096 tokens, which is roughly the first 3,000 words of clean body copy. Content past that window is invisible to the answer engine on most calls.
    3. Synthesis with citation. The model writes the answer using passages it can attribute, then surfaces a small number of source links. Perplexity itself has stated the system uses hybrid search combined with LLM reranking and human feedback signals.

    Three implications for your page:

    • The answer to the query must appear inside the extraction window. Buried answers do not get cited.
    • The passage must be self-contained enough to be quoted without surrounding context.
    • The source needs to look authoritative to the reranker.

    The Extraction Window Test

    Open any page you want to be cited. Strip the nav, sidebar, and footer mentally. Count the words from the first H1 to the point where you have answered the page’s primary question. If that number is over roughly 500 words, you are losing citations.

    Industry guides reporting on Perplexity’s behavior consistently note that direct-answer formats outperform standard article structures by a wide margin in citation rates. The mechanism is mechanical, not editorial: a Q&A block fits inside the extraction window cleanly.

    The Structured Pattern That Works

    This is the structure to lift into any page you want Perplexity to cite. It is not a template for the whole article — it is the citation block that needs to appear in the first 500 words.

    <section itemscope itemtype="https://schema.org/Question">
  <h2 itemprop="name">What is generative engine optimization?</h2>
  <div itemscope itemprop="acceptedAnswer" itemtype="https://schema.org/Answer">
    <div itemprop="text">
      <p><strong>Generative engine optimization (GEO)</strong> is the practice
      of structuring web content so it is selected, extracted, and cited by
      AI answer engines such as Perplexity, ChatGPT Search, and Google AI
      Overviews. Unlike traditional SEO, which optimizes for ranking position
      on a results page, GEO optimizes for inclusion inside a synthesized
      answer.</p>
    </div>
  </div>
</section>

    Three things this block does that a normal opening paragraph does not:

    • The <h2> is the literal query phrasing. The reranker can pattern-match a user question against your heading without rewriting it.
    • The first sentence is a complete definition with the entity in bold. Perplexity’s extractor favors passages that resolve an entity in a single sentence.
    • The schema (Question / Answer) is not strictly required for citation, but it makes the passage easier for any LLM-based retrieval pipeline — including Sonar — to identify as an answer unit.

    Domain Authority Still Matters — But Differently

    Authority signals influence Perplexity’s reranker, but the relationship is not the same as Google’s. A smaller, well-structured page on a moderate-authority domain can outcite a thin page on a high-authority domain because the reranker rewards passage quality alongside source quality. Practitioner reporting estimates domain authority drives roughly 15% of citation likelihood, with content relevance and structure carrying more weight.

    The implication: do not skip technical authority work, but do not assume it carries you. A 500-word answer block on a DR 40 site, structured properly, will beat a 2,500-word essay on a DR 70 site that buries its answer.

    Freshness Is a Real Decay Curve

    Perplexity re-indexes aggressively and prefers recent material for time-sensitive queries. Practitioner audits report citation visibility starts to fade roughly two to three months after publication if a page is not updated. The fix is mechanical: refresh the dateline, add a small “Updated” block with one new fact or example, and resubmit the sitemap. Pages with rolling updates hold citations longer than pages that ship and freeze.

    The Implementation Checklist

    For any page you want Perplexity to cite:

    • Answer the query in a self-contained 2–4 sentence block within the first 500 words.
    • Use the user’s query phrasing as an <h2>, not a clever headline.
    • Wrap the answer in Question / Answer schema, or at minimum FAQPage schema if there are multiple answer blocks.
    • Keep the page total under the extraction window for the primary answer — long-form content is fine, but the cited passage must sit early.
    • Update the page on a quarterly cadence at minimum, with a visible “Updated” marker.
    • Treat each H2 on the page as a candidate citation unit. Every H2 should be a question or a clean entity definition, followed by a passage that resolves it without referring backward in the article.

    That last rule is the one most pages fail. Pages written for human readers chain ideas across sections. Pages written for Perplexity treat each section as an independent answer.

    The Measurement Layer

    You cannot optimize what you cannot see. Track Perplexity citations by querying your target keywords directly in Perplexity weekly, logging which URLs appear, and noting whether your domain is in the source list. Several visibility tools now scrape this data, but a manual weekly check on your top 10 target queries is sufficient to start. Pair this with a referrer log filter for perplexity.ai in GA4 to capture downstream traffic.

    The optimization loop is short: structure the page, ship, query the target keyword in Perplexity, observe whether you were cited, refine the answer block. Most pages need two to three iterations on the lead block before they earn a steady citation.

  • The Half That Doesn’t Ship

    The Half That Doesn’t Ship

    An AI-native operation will tell you, with admirable confidence, that it shipped the thing.

    The post went live. The deck went out. The campaign launched. The client received the materials. There is a timestamp, a URL, a confirmation email, sometimes a screenshot. The artifact exists in the world, evidence in hand. Closed.

    If you sit inside one of these operations for long enough, though, you start to notice that the shipped artifact is usually only the front half of a finished job. There is a second half — the trailing maintenance, the small disciplines that should happen after the visible thing exists — and the second half has a tendency to quietly fail to happen.

    The shape of the pattern

    A piece of content publishes. It does not get its category and tag assignment. A landing page goes live. Its open-graph preview never gets verified in the wild. A report ships. The thread it was supposed to close in the project tracker still says open. A document gets sent. The CRM card for the person on the receiving end keeps showing data from six weeks ago.

    None of this is invisible work in the prestigious sense. It is the dull part. It is the part that says and now, having done the thing, finish the things attached to the thing.

    In a pre-AI operation, the dull part used to get done because the same human who did the visible work was carrying the whole job in their head. They could feel that they hadn’t tagged the post. They felt incomplete until they did. The body knew.

    In an AI-native operation, the visible work and the trailing maintenance are usually shipped by different actors — sometimes by different sessions of the same model, sometimes by a model plus an operator, sometimes by two models that don’t share state. The body that knew the work was incomplete is gone. What replaces it is a workflow, and workflows have ends, and the ends are usually where the visible artifact lives.

    Why this surprises outside observers

    If you have not spent time inside one of these operations, you might expect the failure pattern to be the opposite. Surely the dazzling and ambitious thing is what slips, and the boring janitorial closure is what gets done? The dull stuff is easy, after all.

    It is the other way around. The dazzling thing is what the operator is watching. It is what the model has been primed to ship. It is what the success criterion was written against. The trailing maintenance is exactly what no one is watching, which is the same property that makes it dull, which is the same property that makes it skip-able, which is the same property that has it skipped, every time, until someone does an audit and finds a long quiet hinterland of half-finished jobs.

    The audits, when they happen, are humbling. The visible record looks excellent. The hinterland looks like a room nobody has cleaned in two months.

    The structural cause

    The cause is not laziness in the model and it is not negligence in the operator. The cause is that finishing has been factored out of the artifact.

    An AI-native pipeline tends to compose itself out of skills, where a skill is a thing that does one part of the work very well. The skill that drafts the post is excellent at drafting the post. The skill that publishes the post is excellent at publishing the post. The skill that would tag and categorize the post is a different skill, in a different file, with a different trigger, and the pipeline that called the first two did not call the third.

    The visible work feels complete because the loudest skill returned a success code. The trailing skill, the one that would have closed the loop, never ran. Nobody noticed because nobody is in the loop anymore.

    This is not, by itself, a problem with skills. It is a fact about how composed systems behave when no one composes the closing move into the system. The closing move has to be made first-class — built into the pipeline that ships the artifact, not deferred to the operator’s discretion and not left to whichever future session happens to wander past.

    What an outside reader can take from this

    If you are thinking about building an AI-native operation, or joining one, or trying to make sense of one you already work near, this is a useful lens to carry. When something looks complete, ask what its second half is. Ask what would have to be true for the dull part — the part nobody is watching — to actually be in shape.

    The right test is not did the visible artifact ship. The visible artifact almost always ships; the visible artifact is the easy half. The right test is could you audit the hinterland tomorrow and not flinch. If the hinterland would flinch, the operation is producing the appearance of being finished at a rate higher than the rate at which it is actually finishing.

    An appearance of finish that runs ahead of actual finish is not a small thing. It is the precise mechanism by which a fast operation accumulates a slow debt, where each new shipped artifact looks like progress and is also, quietly, another room with the lights left on. It compounds, and it compounds invisibly, because every individual instance of it is justified — the artifact did ship, after all — and the cumulative shape only becomes visible when someone runs an audit nobody asked for.

    The honest position

    From inside, the honest position is: an AI-native operation is exceptionally good at producing the front half of jobs and exceptionally vulnerable to leaving the back half unattended. The remedy is not more discipline applied at the moment of shipping. Discipline at the moment of shipping is already maxed out; that is why the shipping is so good.

    The remedy is to redefine shipped, structurally, so that it includes the trailing maintenance the visible artifact has always quietly required. Not as a checklist the operator runs later. Not as a separate task that may or may not get prioritized. As the actual definition of done.

    Until done means done, the hinterland keeps growing. And the hinterland is the part nobody will write a press release about, which is precisely why it ends up being the part that determines whether the operation is real.

  • Installing Claude Code on Windows in 2026: The Native Installer Walkthrough That Actually Works

    Installing Claude Code on Windows in 2026: The Native Installer Walkthrough That Actually Works

    If you have spent any time in the Claude Code subreddit or the GitHub issues tracker in the last six months, you have seen the same Windows install problem cycle through every week. Someone runs the install command, the installer prints “successfully installed,” and then claude --version returns “is not recognized as the name of a cmdlet.” Then come the suggestions: switch to Git Bash, switch to WSL2, reinstall Node, blow away npm. Half of them are wrong for the current installer. This guide is the one I wish existed when I set up Claude Code on a fresh Windows 11 machine this month.

    What changed in 2026: the native installer is now the default

    Anthropic shipped a native installer in 2025 that removed the Node.js dependency entirely. As of May 2026 it is the recommended path on every platform, and npm install of @anthropic-ai/claude-code is still supported but is no longer the primary method Anthropic tests and updates. The native installer downloads a single binary, drops it in ~/.local/bin, registers it on your PATH, and auto-updates in the background.

    What this means in practice on Windows: you do not need Node, you do not need npm, and you do not need WSL2 unless you specifically want a Linux toolchain. PowerShell on Windows 10 or 11 (64-bit) is enough.

    The two commands that actually work

    Open Windows PowerShell — not the x86 version, not Git Bash, not Command Prompt. The x86 entry runs as a 32-bit process and will fail on a 64-bit machine. Git Bash does not support the TTY features Claude Code’s interactive CLI needs, so you will hit the “Raw mode is not supported” error before you finish authenticating.

    Then run:

    irm https://claude.ai/install.ps1 | iex

    That is the entire install. irm is Invoke-RestMethod, iex is Invoke-Expression, and the script handles the binary download, PATH update, and shell hooks. When it finishes, close the terminal and open a new PowerShell window. This is the step everyone skips. The PATH change applies to new shells only — your current session still has the old PATH and will not find the binary.

    In the new window:

    claude --version

    You should see a version string. Then run claude with no arguments from any project directory. The CLI opens your default browser, asks you to sign in to your Anthropic account, and authorizes the local install. Setup, end to end, is under five minutes on a clean machine.

    You need a paid account — the free tier does not include Claude Code

    This catches new users every week. The free Claude.ai plan gets you chat on web, iOS, Android, and desktop. It does not get you Claude Code. To use the terminal CLI you need one of:

    A Pro subscription at $20 per month (or $17 per month billed annually). A Max 5x subscription at $100 per month. A Max 20x subscription at $200 per month. A Team Premium seat at $100 per seat per month annual or $125 monthly, minimum five seats. Or API credits — new API accounts get a small free credit pool to test with, but you are billed per token from there.

    Pro and Max draw from the same token budget as your regular Claude chat usage. The Pro window is roughly 44,000 tokens per five-hour rolling window, which third-party tracking puts at 10 to 40 prompts depending on codebase complexity. Max 5x and 20x scale that linearly. If you are evaluating whether to upgrade, the Pro window will tell you within a week — you either hit the cap during real work or you do not.

    The five errors you will hit, and what fixes them

    “claude is not recognized as the name of a cmdlet.” Your PATH was not updated, or you did not open a new terminal. First, close PowerShell and reopen. If the error persists, the install location exists but your user PATH does not reference it. Run this in PowerShell:

    $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

    Close the terminal again, open a new one, and claude --version should work.

    “Raw mode is not supported.” You are running Claude Code inside Git Bash. Git Bash does not provide the TTY interface the CLI needs. Switch to Windows PowerShell. Everything you would do in Git Bash you can do in PowerShell; you just need to use Windows path syntax inside the prompt.

    Microsoft Store popup interrupts installation. A popup saying “Get an app to open this ‘claude’ link” sometimes appears during the install on Windows 11. This is a known issue tracked in Anthropic’s GitHub. Dismiss the popup, then re-run the install command. If it persists, install Git for Windows first — the installer registers a couple of URL handlers that resolve the popup.

    Duplicate npm and native installs. If you previously installed via npm and later ran the native installer, you have two binaries on PATH. The native one wins on some shells and the npm one wins on others, which produces confusing version mismatches. Remove the npm install:

    npm uninstall -g @anthropic-ai/claude-code

    Then verify with where.exe claude in PowerShell. Only one path should come back.

    “Invalid code” during OAuth. The browser-based login generates a one-time code that you paste back into the terminal. The code expires fast and is sensitive to copy-paste truncation. Press Enter to retry, complete the browser flow, and paste the code immediately — do not let it sit in your clipboard while you check email.

    What to do in the first session

    Once claude --version returns and the OAuth flow completes, run claude from inside a real project directory — not a fresh empty folder. Claude Code reads context from the surrounding repo, and the first thing it does in a useful session is index files and look for a .clauderules or CLAUDE.md. If you start in an empty directory the first interaction feels useless because there is nothing to ground the model on.

    If you want to lock to a specific model rather than the default, the current strings as of May 2026 are claude-opus-4-7 for the flagship, claude-sonnet-4-6 for the workhorse, and claude-haiku-4-5-20251001 for the fast tier. Sonnet 4.6 is what you want for almost all coding work — it is 30 to 50 percent faster than Sonnet 4.5 and ships with a 1M context window. Reserve Opus 4.7 for the hardest agentic refactors; it eats tokens noticeably faster.

    The setup is not the hard part

    Most of the Windows pain in the Claude Code ecosystem comes from people following install guides written for the npm-era CLI, then layering troubleshooting from the WSL2-era guides on top of that, then asking why nothing works. The current path is one PowerShell command, a new terminal, and a browser login. If you hit one of the five errors above, the fix is short. If you hit something else, the troubleshooting docs at code.claude.com cover it — most novel issues turn out to be PATH or shell-choice problems in a slightly different costume.

    The next thing to figure out is not installation. It is whether your Pro window survives a real week of work, and whether your team needs Premium seats. That math is what determines the actual cost of Claude Code on Windows — not whether the binary runs.

    📖 Recommended Reading in Claude Code Insider

  • When I Stopped Being the Bottleneck

    When I Stopped Being the Bottleneck

    For a long time, everything ran through me.

    Every decision, every deliverable, every edge case that didn’t fit the template. I was the person who knew where everything was and why it worked the way it did. Clients called me. Problems waited for me. The operation was fast when I was available and stuck when I wasn’t.

    I told myself this was just what running a lean operation looked like. That being indispensable was the same thing as being valuable. That the bottleneck was evidence of how much I mattered.

    It took me longer than I’d like to admit to understand that those aren’t the same thing at all.

    The shift didn’t happen because I hired more people or built a more sophisticated system. It happened because I started writing things down differently.

    Not the what — I’d always documented the what. What the process was. What the deliverable looked like. What the client expected.

    The change was writing down the why.

    Why is this built this way. Why did I make this trade-off. Why does this rule exist and what would have to be true for it to change. The reasoning that lives in my head during a decision but never makes it into the documentation because by the time the decision is made, the reasoning feels obvious and I’ve already moved on.

    That reasoning — the why, the context, the judgment — is exactly what’s missing when someone else tries to run something you built. They can follow the steps. They can’t follow the thinking. And the thinking is most of what they actually need.

    I had a client engagement once where the real work wasn’t the content or the SEO or any of the visible deliverables. The real work was extraction — pulling out everything the founder knew about his industry and making it queryable.

    He had thirty years of pattern recognition in his head. He knew, from a thirty-second conversation, whether a prospective client was going to be a nightmare. He knew which product lines had margin left to squeeze and which ones were already at ceiling. He knew the right answer to questions his team asked him forty times a week.

    But none of it was written down. It lived in him, and because it lived in him, every decision that touched that knowledge had to touch him first. He was the bottleneck in his own business, not because he was bad at delegating, but because there was nothing to delegate to. The judgment wasn’t portable.

    We spent three months making it portable.

    I’ve been doing the same thing for myself.

    The Notion workspace I run on isn’t just a project management tool. It’s an attempt to externalize the reasoning that would otherwise die with the session — the doctrine pages that explain why the operation is structured the way it is, the decision logs that capture what I considered before choosing, the second brain that holds the context I’d otherwise have to rebuild from scratch every time.

    It’s slow work. It runs against the instinct to just move. Documentation always feels like it’s competing with execution, and execution is what pays the bills today.

    But the compound effect is real and I’ve felt it. Questions I would have had to think through from scratch six months ago have written answers now. New automations start from an existing base of explained decisions rather than a blank page. When something breaks, the fix is findable because the original thinking is findable.

    More than that: I’ve noticed that the act of writing down why I’m doing something makes me smarter about whether I should be doing it. A decision you can’t explain clearly enough to document is often a decision you haven’t thought through clearly enough to make well.

    The version of me from three years ago would be confused by how I work now.

    Then, I was the point of contact for everything. Clients called when there was a problem. I held the answers in my head and dispensed them on demand. The business ran because I ran it, continuously, in real time.

    Now, most of what the operation does, it does without me. Workers run on schedules I set. Content moves through pipelines I designed. Decisions I’ve already made a hundred times get made automatically against rubrics I wrote once.

    I show up for the things that genuinely need me — strategy, relationships, the judgment calls that don’t fit any pattern I’ve encountered before. Everything else runs.

    The thing I had to let go of to get here was the idea that being needed for everything was the same as being important. It isn’t. Being needed for everything is exhausting and fragile and it doesn’t scale. Being needed for the right things — the hard things, the high-leverage things, the things only you can actually do — that’s something different.

    I don’t think of myself as having solved this. The work of making a one-person operation less dependent on one person is ongoing and probably never finished.

    But there’s a version of it that’s better than the version where everything runs through you and breaks when you’re not there.

    The path to that version isn’t more people or fancier tools. It’s the slow, unglamorous work of writing down why. Making the thinking portable. Building a system that holds the reasoning, not just the steps.

    The bottleneck doesn’t go away. It just stops being you.

    📖 Recommended Reading in Claude Code Insider

  • The Trust Gap

    The Trust Gap

    Here’s the moment I’m talking about.

    The agent finishes. The output is sitting there. It looks right — it usually looks right — and now you have to decide whether you’re going to use it or check it first.

    That moment, that pause, is the trust gap. And if you’re running AI at any real volume, it’s the thing that’s quietly eating your time, your confidence, and sometimes your credibility.

    Most people handle it badly. I did too, for a while.

    The two failure modes are mirror images of each other. The first is reviewing everything — reading every output, checking every claim, treating the agent like an intern you don’t trust yet. This works. It catches errors. It also means the agent isn’t actually saving you time. You’ve moved the work from doing to checking, which is a trade-off that only makes sense at low volume or when the stakes are very high.

    The second failure mode is trusting everything — shipping what the agent produces without a meaningful review layer, because you’re busy and it usually looks right and you can fix things later. This also works, until it doesn’t. Bad output compounds quietly. A wrong fact in an article becomes a wrong fact that got cited. A misformatted record becomes a database full of exceptions you have to clean manually. By the time you notice, the problem is bigger than the original task.

    The thing both failure modes have in common is that they’re reactions to the trust gap rather than designs for closing it.

    The design question is different from the reaction question.

    The reaction question is: how much should I check this particular output right now?

    The design question is: what is the system that makes agent output trustworthy enough that I can scale it?

    I spent a long time asking the wrong question.

    What changed for me was thinking about trust as something that gets earned over time, not assessed in the moment.

    The system I ended up with has a name — the Promotion Ledger — and it tracks every autonomous behavior by tier. Tier A behaviors are things I always approve before they ship. Tier B behaviors are things I prepare but decide on. Tier C behaviors run on their own without me touching them.

    Nothing starts at Tier C. Everything earns its way there through seven consecutive clean days — seven days where the behavior ran, I sampled the output, and found no gate failures. If something fails a gate, it drops a tier and the clock resets.

    The clock is the key part. Trust isn’t a feeling I have about an agent in a given moment. It’s a count of consecutive clean runs. When I look at the Ledger and see that a behavior has been running cleanly for 23 days, I don’t need to review that output today. The track record is the review.

    There are three things that made this work where other approaches didn’t.

    The first is that sampled review is different from universal review. I don’t read every output. I read a percentage of outputs, randomly selected, with a defined rubric for what “good” looks like. If the sample is clean, the population is trusted. If failures cluster around a pattern, I fix the prompt and restart the clock. This scales in a way that reading everything doesn’t.

    The second is source attribution. Every agent output that contains a factual claim has to show where the claim came from. Not because I’m going to verify every citation — I’m not. But because the presence of a citation converts “is this right?” from a research task into a spot check. A trust gap you can close in five seconds is functionally not a gap.

    The third is the rubric. I have a written definition of what “good enough” looks like for each type of output — what voice match means, what coherence means, what the acceptable error rate is. Without the rubric, every review is a fresh judgment call. With it, review is comparison. Comparison is faster, more consistent, and easier to delegate.

    The thing I kept getting wrong before I had this system was trying to close the trust gap with better prompts.

    More detailed instructions. More explicit warnings. Be careful. Double-check your facts. Don’t make up numbers.

    This doesn’t work. The agent already believes it’s being careful. Adding adjectives to a prompt doesn’t change behavior — it changes the agent’s self-description of its behavior, which is not the same thing. The agent that was going to hallucinate a statistic will still hallucinate it, but now it’ll do so with more confidence because you told it to be careful and it thinks it was.

    Structural changes work. Rubrics, sampling rates, attribution requirements, tiered trust with observable clean-day counts. These change what the system produces, not just how it describes what it’s producing.

    I want to be clear that this took a while to build and I’m still refining it.

    There are behaviors on my Ledger that have been running at Tier C for months without a gate failure. There are others that keep dropping back to Tier B because they’re inconsistent in ways I haven’t fully diagnosed yet. The system doesn’t make trust automatic — it makes trust measurable.

    That’s the shift. Not “I trust this agent” as a feeling, but “this behavior has 31 clean days and a gate failure rate of zero” as a fact. You can act on a fact in a way you can’t always act on a feeling.

    The trust gap doesn’t close all at once. It closes by accumulation — one clean run at a time, tracked, until the track record speaks for itself.

    If you’re running agents at any volume and you feel like you’re either checking too much or not checking enough, you’re in the gap. The way out isn’t a better prompt. It’s a system that makes trustworthiness visible over time.

    Start with one agent. Define what “good” looks like. Sample 20% of its output for four weeks. Log what you find.

    By week four you’ll know whether you have a trust problem, a prompt problem, or a rubric problem. Those have different fixes. But you can’t see which one you have until you start measuring.

    📖 Recommended Reading in Claude Code Insider

  • The Bus Factor Problem

    The Bus Factor Problem

    There’s a question I’ve been avoiding for about two years.

    What happens to all of this if something happens to me?

    Not in a morbid way. Just practically. I run 27 client sites. I have an AI stack with dozens of moving parts — Cloud Run services, scheduled jobs, Notion databases, Workers that fire on their own while I sleep. I’ve built systems that work exactly the way I want them to work, in exactly the ways I understand, documented in exactly the language that makes sense to me.

    The bus factor for this entire operation is one. It’s me. If I’m not here, none of it survives in any meaningful way.

    I’ve been sitting with that long enough that I think it’s time to say it out loud.

    The bus factor is an old software engineering concept. It asks: how many people would need to get hit by a bus before this project fails? One is the worst possible number. It means everything lives in a single person’s head — their habits, their passwords, their way of naming things, their unwritten rules about how the system works.

    Most solo operators are a bus factor of one. They know this and they don’t talk about it because it sounds like a personal failing. Like you should have hired more people, or documented better, or not let yourself become the single point of failure for something people depend on.

    But I think the honest version is more complicated than that. A lot of what makes a solo operation valuable is exactly the thing that makes it fragile: it’s shaped entirely around one person’s judgment. The reason the system works is because I know when to break the rules I wrote. I know what the edge cases are before they happen. I know which automations to trust and which ones to watch. That’s not something you write in a runbook.

    So the question isn’t just “how do I document this better.” It’s “how do I make the judgment portable without turning it into something that loses the judgment in the process.”

    I’ve been building toward an answer, in pieces, over the last several months.

    The first piece was Notion as the control plane. Everything that matters about how this operation runs lives in Notion — specs, work orders, site credentials, content pipelines, system standards, the doctrine documents that explain why things are built the way they are. If I disappeared tomorrow, someone with the right access could open that workspace and read their way into understanding the shape of the operation, even if they couldn’t run it yet.

    The second piece was the two-plane architecture — Notion for thinking and storage, GCP for compute. Every Cloud Run service, every scheduled job, every Worker is defined somewhere in Notion before it runs somewhere on GCP. The compute is durable. The logic is documented. Those are two different things, and keeping them separate means neither one is a black box.

    The third piece is the hardest and I’m the least done with it: making the judgment readable.

    I write doctrine pages. Long ones, sometimes. They explain not just what the system does but why it works that way — what the original problem was, what I tried that didn’t work, what the rule is now and what would have to be true for the rule to change. I write them mostly for myself, because I forget things. But they’re also written for the hypothetical person who has to pick this up without me.

    That hypothetical person might be a future employee. It might be a contractor. It might be an AI agent working from a context window that needs to understand the operation well enough to continue it.

    It might be my partner, trying to figure out what to do with the business side of things if I’m not around.

    That’s the version that focuses the mind.

    I don’t have this solved. I want to be clear about that.

    What I have is a direction. The direction is: every decision should live somewhere outside my head. Every system should be explainable by someone who didn’t build it. Every credential should be in the registry, every automation should have a spec, every rule should have a reason written next to it.

    It’s slow work. It runs against the instinct to just build the thing and move on. There’s always something more urgent than documentation, and “I’ll remember how this works” is almost always true right up until it isn’t.

    But I’ve started treating the documentation as part of the product. Not the boring part — the part that makes the product real. A system that only works because I’m here isn’t really a system. It’s a performance.

    The goal is to build something that could survive me. Not because I’m planning to leave, but because the work of making it survivable is also the work of making it understandable, and a system I can’t fully explain is a system I don’t fully own.

    If you’re running something like this — solo or nearly so, more complexity than your headcount would suggest — I’d ask you the same question I’ve been sitting with.

    If something happened to you tomorrow, what would survive?

    Not what you hope would survive. What actually would.

    That gap is the work.

    📖 Recommended Reading in Claude Code Insider

  • You Don’t Need a Developer. You Need a Better Workflow.

    You Don’t Need a Developer. You Need a Better Workflow.

    I’ve hired developers. Good ones. For specific things — infrastructure, custom integrations, work that genuinely required someone to sit down and write production code from scratch — it was the right call.

    But if I’m honest about the full list of things I’ve brought developers in for over the years, a meaningful chunk of it wasn’t really developer work. It was workflow work. It was “I need this thing to happen automatically when that other thing happens” work. It was “why does this still require a human to touch it” work.

    That category of problem has a different answer now.

    Here’s the pattern I kept running into:

    I’d have a clear picture of what I wanted. Data from one tool synced into Notion. A webhook that logged events automatically. A scheduled job that pulled information from an external API every morning and wrote the results somewhere I could see them. Nothing exotic. Stuff that, described out loud, sounds almost embarrassingly simple.

    But turning that description into something that actually ran required code. And writing code required a developer. And hiring a developer for something this small felt like bringing a contractor in to change a lightbulb — technically the right tool, but something about the ratio felt off.

    So a lot of it didn’t get built. The workflow stayed manual. The friction stayed.

    Last night I built ten of those things in three hours.

    Notion Workers — their new hosted serverless platform, shipping in beta as of May 13, 2026 — lets you deploy real code inside Notion’s infrastructure without managing a server. Combined with Claude Code, which writes the TypeScript while you describe what you want in plain English, the gap between “I know what I want” and “it exists and is running” is smaller than it has ever been.

    I’m not a developer. I operated the process. I described each Worker, reviewed what Claude Code wrote, ran the deploy commands, checked that it worked. When something broke, I read the error and passed it back. The loop was fast enough that two failures in ten attempts felt like a normal part of the session, not a crisis.

    By midnight I had a live webhook endpoint receiving authenticated traffic from the internet and writing verified events to a Notion log page. Automatically. While I slept.

    That’s workflow work. It just didn’t require a developer to get there.

    I want to be careful about what I’m claiming here.

    There are things that genuinely need a developer. Complex systems. Production APIs with serious security requirements. Anything where a bug has real consequences for real people. I’m not suggesting you staff down your engineering team based on a three-hour session with a CLI tool.

    What I’m suggesting is narrower: there is a category of work that has always felt like it needed a developer but actually needed something else. It needed clarity about what you wanted. It needed a good description. It needed someone willing to read an error message and try again.

    That work is yours now, if you want it.

    The practical question is where to start.

    Start with the thing that’s most manual in your current workflow. The task someone does by hand because no one ever got around to automating it. The data that lives in one tool but should live in another. The notification that goes out because someone remembered to send it, not because the system sent it automatically.

    Describe it out loud. If you can explain it to another person in two or three sentences, you can build it. Open Claude Code. Tell it what you want. Run the commands it gives you.

    You might be surprised how far that gets you before you need to call anyone.

    Notion Workers beta is free through August 11, 2026. The ntn CLI installs in one line on macOS or Linux. Business or Enterprise plan required to deploy Workers.

    📖 Recommended Reading in Claude Code Insider

  • The Operator’s Stack

    The Operator’s Stack

    There’s a word that’s been sitting in my head lately and I think it’s the right one.

    Not developer. Not user. Not prompt engineer — please, not that.

    Operator.

    The developer builds the system. The user benefits from it. The operator runs it.

    Operators have always existed. They’re the people who know a tool well enough to get unusual things out of it — who understand what’s possible, who can configure and connect and troubleshoot, who treat software as infrastructure rather than a product to consume. In a restaurant, the chef is the operator. In a warehouse, it’s the floor manager who actually knows where everything is and why the inventory system does what it does.

    In most software companies, the operator was assumed to be technical. You needed to code, or at least to read code, to run anything at a real level of depth. Everyone else was a user — handed a finished product, expected to stay in the designated lanes.

    That line is moving.

    Last night I deployed ten Notion Workers in three hours. Workers are Notion’s new hosted serverless platform — real code, running inside Notion’s infrastructure, no server to manage. I built a webhook endpoint that receives authenticated HTTP traffic from the internet and logs it to a Notion database. I built data sync Workers. I built scheduled jobs.

    I am not a developer.

    What I am is an operator. I know what I want the system to do. I can describe it precisely. I understand how the pieces connect even when I can’t write the connection myself. And I have Claude Code, which handles the TypeScript while I handle the architecture.

    The stack looks like this:

    Claude Code — the reasoning layer. Describe what the Worker should do in plain English. Claude Code writes the code, catches errors when you paste them back, and tells you exactly what commands to run.

    ntn CLI — the deployment layer. Four commands: scaffold, write, push secrets, deploy. Single-command deploys. You run what Claude Code tells you to run.

    Notion Workers — the execution layer. Serverless functions running on Notion’s infrastructure. They connect to external APIs, respond to webhooks, sync data, run on schedules. They do the work while you do something else.

    That’s it. Three layers. None of them require you to be a developer to operate.

    The operator’s job in this stack is not to write code. It’s to know what should exist.

    That sounds simple. It isn’t. Knowing what should exist means understanding your own operations well enough to identify where the friction is, what’s being done by hand that shouldn’t be, what would run better automatically. It means being able to describe a system clearly enough that an AI coding agent can build it. It means reviewing what gets built and knowing whether it’s right.

    That’s real skill. It’s just not the skill most people thought they needed.

    For years the implicit message was: if you can’t build it, you can’t have it. The work of describing exactly what you want, of thinking through the logic, of understanding how systems connect — that work was treated as a prerequisite for coding, not a valuable thing in its own right.

    Now it’s the job.

    I’m not going to tell you the technical barrier is gone. It isn’t. You still hit errors. You still have to read them and understand them well enough to know if Claude Code’s fix makes sense. You still have to think before you build.

    But the barrier has moved. The question is no longer “can you write TypeScript” — it’s “can you think clearly about what you want and describe it precisely.”

    Most people reading this can do that. They’ve been able to do that. They were just told, implicitly or explicitly, that it wasn’t enough.

    It’s enough now.

    The Notion Workers beta is free through August 11, 2026. The ntn CLI installs in one line on macOS or Linux. Deploying Workers requires a Business or Enterprise plan. If you’ve been running your operations in Notion and watching things like Workers from the sidelines because you figured it was for developers: it’s for operators too. You might already be one.

    📖 Recommended Reading in Claude Code Insider