Author: Will Tygart

  • Fisherman Jack’s Is the Everett Waterfront Restaurant Doing Dim Sum Better Than You Expect

    Fisherman Jack’s Is the Everett Waterfront Restaurant Doing Dim Sum Better Than You Expect

    Q: Is Fisherman Jack’s on the Everett waterfront worth the trip?
    A: Yes — Fisherman Jack’s at 205 Seiner Dr, Suite 101, Everett, WA 98201 is one of the only sit-down dim sum restaurants on the Port of Everett waterfront, serving Asian-seafood fusion with marina views. Locals repeatedly recommend the Jack’s miso black cod, Rainier clams with Chinese sausage, and the Dungeness crab rangoon. Open Tuesday through Sunday, closed Monday.

    We Keep Going Back to Fisherman Jack’s — And Here’s Why That Matters

    There’s a specific category of Everett restaurant we’ve come to appreciate: places that could easily coast on their view and don’t. Fisherman Jack’s is squarely in that category. Sitting at the Port of Everett’s Waterfront Place with the marina out the window and the Olympics across the Sound on a clear day, the restaurant has the kind of real estate where mediocre food would still pull tourists in on a Saturday night. That’s not what this place is.

    Fisherman Jack’s is an upscale Asian-seafood fusion restaurant that does dim sum, coastal Chinese dishes, and a genuine Pacific Northwest seafood menu — and it does them at a level most waterfront restaurants don’t bother with. If you live in Everett and you still haven’t been, you’re missing one of the two or three best things that have happened to the waterfront dining scene in the last five years.

    The Basics: Address, Hours, Parking

    Address: 205 Seiner Dr, Suite 101, Everett, WA 98201
    Phone: (425) 610-3616
    Website: fishermanjacks.com
    Hours: Tuesday–Thursday and Sunday, 11:30 AM–10:00 PM; Friday–Saturday, 11:30 AM–11:00 PM. Closed Monday.
    Price range: $$–$$$ (entrées $18–$42; dim sum $8–$16 per plate)
    Parking: Free waterfront parking along Seiner Dr and in the Waterfront Place lots. Weekends can fill up around sunset — aim to arrive before 6 PM or be prepared to walk a block.

    The restaurant is named after owner Jack Ng, whose love of Pacific Northwest seafood shaped the whole concept. It opened in late 2023 as one of the anchor restaurants at the Port’s Waterfront Place redevelopment — the same block where Tapped Public House, Bluewater Organic Distilling, and Scuttlebutt Brewing’s downtown taproom now live. Seiner Drive has become the most interesting half-block of food in Everett, and Fisherman Jack’s is the heavyweight of the group.

    What to Order (And What’s Worth the Hype)

    Start With the Dim Sum

    This is the move. Fisherman Jack’s is one of the only restaurants north of Seattle doing proper sit-down dim sum at dinner hours — not the cart-service format you’d get in the ID, but a menu of handmade dumplings, buns, and small plates that come out fast and hot. Order the Dungeness crab rangoon — we had doubts about a crab rangoon on a serious menu and the doubts were wrong. The filling is actual Dungeness, not the pink stuff, and the wrapper shatters the right way.

    Also get the shrimp and pork siu mai, the spicy wontons, and the chocolate dumplings for dessert if you’re feeling adventurous. The chocolate dumplings are weird. We kept eating them.

    Jack’s Miso Black Cod Is the Signature Dish

    If you’re only going once, order the miso black cod. It’s the dish that turns up in every positive review online, and it deserves that. Sablefish (black cod) is the richest, butteriest fish in Pacific Northwest waters, and the miso marinade at Fisherman Jack’s caramelizes just enough under the broiler to give it that classic Nobu-adjacent finish without being overly sweet. It flakes apart with a chopstick. It tastes like something you’d get at a Belltown tasting menu for twice the price.

    The Rainier Clams Are a Surprise Winner

    A Pacific Northwest classic with a Chinese twist: steamer clams cooked with lap cheong (Chinese cured sausage), garlic, onion, and Rainier beer. The broth is the reason to order it — lighter than a traditional clam sauce, with the sweet porkiness of the sausage threading through. Ask for extra bread. You’ll want to sop.

    If You’re Not in a Seafood Mood

    The Mongolian beef is tender and slightly sweet, sliced against the grain so it cuts with a chopstick. The Kung Pao tofu is a legitimate option for vegetarians (not an afterthought). The coconut curry mussels lean Thai but use PNW mussels and work better than they have any right to.

    The Drinks Program Is Better Than It Needs to Be

    Fisherman Jack’s has a tight craft cocktail list that leans tropical — think rum-forward drinks with fresh citrus — plus a draft list with local beers from At Large, Scuttlebutt, and a rotating PNW tap. The wine list is short but well-chosen and won’t embarrass anyone. Our house recommendations: the Oasis (light rum, pineapple, lime) at sunset, or the Darken the Ship cold brew martini after dinner if you still have it in you. They pair surprisingly well with the black cod.

    When to Go

    Go on a weeknight if you can. Tuesday through Thursday between 5:30 and 7:00 PM gives you the sunset over the marina without the Friday-night wait. The lighting inside is warm and low, the room stays quiet enough to have a conversation, and the kitchen has time to plate like they care.

    Weekends get busy — make a reservation through OpenTable or the restaurant website. Walk-ins on a Saturday at 7 PM are a gamble, especially in summer when the waterfront is packed. Happy hour isn’t the restaurant’s strength; we’d go for a full dinner or not at all.

    Who Fisherman Jack’s Is For

    This is a date-night restaurant, a visiting-parents restaurant, and an anniversary-but-you-don’t-want-to-drive-to-Seattle restaurant. It’s not a casual weekday lunch spot — that’s what Scuttlebutt and Tapped next door are for. Bring someone you want to impress without having to explain why you drove to Everett to do it.

    Families work too if you come early. The menu has enough non-seafood options (Mongolian beef, chicken dishes, fried rice) that picky eaters can stay happy while the rest of the table chases the black cod.

    What Fisherman Jack’s Means for Everett’s Dining Scene

    For a long time, the serious answer to “where should we go for dinner that isn’t a chain” in Everett was Anthony’s HomePort, Emory’s on Silver Lake, or driving 40 minutes to Edmonds or Seattle. That equation has changed — and Fisherman Jack’s is one of the main reasons why. Alongside The Net Shed Fish Market & Kitchen on Colby, the new waterfront brewery taprooms, and the Millwright District build-out, the city now has a dining tier that can hold its own against bigger neighbors to the south.

    Three months after our first visit, we’ve been back five times. That’s the real review.

    Frequently Asked Questions

    What kind of cuisine is Fisherman Jack’s?

    Asian-seafood fusion. The menu centers on dim sum, coastal Chinese dishes like Szechuan sea bass and Mongolian beef, and Pacific Northwest seafood preparations including black cod, Dungeness crab, Rainier clams, and steamed oysters.

    Does Fisherman Jack’s take reservations?

    Yes — through OpenTable and on their website at fishermanjacks.com. Weeknights are usually fine for walk-ins before 6 PM; Friday and Saturday nights you’ll want a reservation.

    Is there parking at Fisherman Jack’s?

    Yes. Free parking is available along Seiner Drive and in the Port of Everett’s Waterfront Place parking lots. On busy summer weekends, the closest lots fill up — plan on a short walk.

    Does Fisherman Jack’s have vegan or vegetarian options?

    Yes. The menu has impossible dumplings, veggie dumplings, Kung Pao tofu, and several vegetable-forward dim sum plates. Vegans have a real meal available; it’s not an afterthought.

    Is Fisherman Jack’s kid-friendly?

    Yes, especially early in the evening. Early dinner (5:00–6:30 PM) is a good time for families. The menu has non-seafood options for picky eaters, including Mongolian beef, chicken dishes, and fried rice.

    What’s the best dish at Fisherman Jack’s?

    The miso black cod is the signature entrée and the dish most regulars recommend first. For the dim sum menu, the Dungeness crab rangoon and shrimp and pork siu mai are the consistent winners. The Rainier clams with Chinese sausage are the surprise of the menu.

    How expensive is Fisherman Jack’s?

    Expect to spend $40–$70 per person for dinner with a cocktail, depending on how heavy you go on the dim sum and whether you get the black cod. Entrées run $18–$42; dim sum plates run $8–$16. It’s priced as a date-night restaurant, not a weekday lunch spot.

  • The Agency Stack in 2026: Notion + Claude + One Human

    The Agency Stack in 2026: Notion + Claude + One Human

    I’m going to describe the stack I actually run, and then I’m going to tell you honestly whether you should copy it.

    Most writing about “AI agencies” in April 2026 is either pitch deck vapor or hedged-everything consultant speak — pieces that tell you “AI is transforming agencies” without telling you which tools, which workflows, which tradeoffs. This article is the opposite. I’m going to name specifics. I’m going to say what’s working. I’m going to say what isn’t. I’m going to skip the part where I pretend this is a solved problem, because it isn’t, and pretending is how operators who listened to the pitch deck end up eighteen months into a rebuild.

    The stack that follows is what a real, paying-bills agency runs to manage dozens of active properties, real client relationships, and a content production operation that ships every day — with one human in the operator chair. It is not hypothetical. It is also not recommended for everyone, which is the part most of these articles leave out.

    Here’s the real version. You can decide whether it’s for you when we get to the bottom.


    The one-line version of the stack

    Notion is the control plane. Claude is the intelligence layer. A handful of operational services run the work. One human makes the calls.

    That’s it. That’s the whole stack at the summary level. Everything that follows is specificity about what each of those pieces does, why it’s there, and what happens when you try to run a real business through it.

    The four pieces are load-bearing in different ways. Notion holds the state of the business — what’s happening, what’s decided, what’s next. Claude provides the judgment and the synthesis when judgment is needed. The operational services (publishers, research tools, deployment pipelines) do the deterministic work that judgment shouldn’t be wasted on. The human reads, decides, approves, and occasionally gets out of the way.

    Fifteen years ago the same agency would have needed forty people. Ten years ago it would have needed twenty. Five years ago it would have needed eight. In April 2026 it needs one human plus the stack. That’s the thesis. The question is whether you can actually run it that way.


    What “AI-native” actually means in this context

    The phrase “AI-native” has been worn out enough that I need to be specific about what I mean.

    AI-native doesn’t mean “uses AI tools.” Every agency uses AI tools. Every freelancer uses AI tools. That bar is on the floor.

    AI-native means the operating model of the business assumes AI is a teammate, not a productivity tool. AI is in the loop on strategic thinking. AI is reading the state of the workspace and synthesizing it. AI is drafting, reviewing, triaging, and sometimes deciding — with human oversight, but as a continuous participant, not an occasional assistant you turn to when you get stuck.

    The practical difference: an agency that uses AI tools works the way agencies have always worked, but with ChatGPT open in a tab. An AI-native agency has rebuilt its workflows around the assumption that there’s a persistent intelligence layer in the substrate of the business.

    The stack below is what the second version looks like when you commit to it.


    The control plane: Notion

    Notion is where I live during the working day. Not where I put things when I’m done with them — where I actually do the work.

    The workspace is organized around the Control Center pattern I’ve written about before. A single root page that surfaces the live state of the business: what’s on fire today, what’s progressing, what’s waiting on me, what the week’s focus is. Under it sits a database spine that maps to the actual operational objects — properties, clients, projects, briefs, drafts, published work, decisions, open loops. Each database answers a specific question someone running the business would ask regularly.

    Every meaningful page in the workspace has a small JSON metadata block at the top — page type, status, summary, last updated. That metadata block is for the AI, not for me. It lets Claude read the state of a page in a hundred tokens instead of three thousand. Across a workspace of thousands of pages, the compounding context savings are enormous, and it changes what Claude can realistically see in a session.

    The workspace is sharded deliberately. The master context index lives as a small router page that points to larger domain-specific shards. When Claude needs to reason about a specific area of the business, it fetches the shard for that area. When it needs the whole picture, it fetches the router. This is not a product feature anyone has written about — it’s a pattern I arrived at after the main index page got too large to fit into Claude’s context window without truncation. It works. It’s probably what a lot of operators will end up doing.

    What Notion is great at: holding operational state, being legible to both humans and AI, letting you traverse the business by asking questions of the workspace rather than navigating folders, integrating cleanly with Claude via MCP, running background rhythms through Custom Agents.

    What Notion is not great at: being a database in the performance sense (anything heavy goes somewhere else), being the source of truth for code (version control is), being the source of truth for financial transactions (a real accounting system is), being reliable as the only source for anything mission-critical (it has an outage SLA, not an uptime guarantee).

    The rule I follow: Notion holds the operating company. It does not hold the substrate the operating company depends on. That distinction is what keeps the pattern stable.


    The intelligence layer: Claude

    Claude is the AI I actually run the business with. Not because Claude is strictly better than the alternatives at every task — at this point in 2026 the frontier models are all highly capable — but because Claude’s design posture matches what an operator actually needs.

    Specifically: Claude is thoughtful about uncertainty, tells me when it doesn’t know, asks for clarification instead of fabricating, and has a deep integration with Notion via MCP that makes the workspace-and-AI pattern actually work. Those qualities are worth more to me than any single-task benchmark. An AI that sometimes gets things wrong but tells me when it’s uncertain is far more useful than an AI that confidently hallucinates.

    The intelligence layer shows up in three configurations:

    Chat Claude — what I use for strategic thinking, drafting, review, and synthesis. A conversation on claude.ai or the desktop app with the Notion MCP wired in, so Claude can reach into the workspace to ground its answers in real context. This is where the high-judgment work happens. When I’m making a decision, I work through it in a Claude conversation before I commit to it.

    Claude Code — the terminal-based version that lives at the intersection of code and agent. This is where the more technical work happens — building publishers, writing scripts, managing infrastructure, executing multi-step workflows that touch multiple systems. Claude Code reads my codebase, reaches into Notion when it needs to, calls external services through MCP, and writes back run reports.

    Notion’s in-workspace AI (Custom Agents and Notion Agent) — the on-demand and autonomous agents that live inside Notion itself. These handle the rhythms: the daily brief that’s written before I wake up, the triage agent that sorts whatever lands in the inbox, the weekly review that gets drafted on Friday. I didn’t build these to be clever. I built them because I was doing the same small synthesis tasks over and over, and Custom Agents let me stop.

    Three configurations, three different jobs. Each one’s strengths map to a different kind of work. Together they cover the whole territory.

    What Claude is great at: synthesis across real context, drafting with judgment, reasoning through decisions, catching inconsistencies in my thinking, executing defined workflows with honest failure modes.

    What Claude is not great at: being the last line of defense on anything (always have a human gate), handling workflows where one error compounds (use deterministic tools for those), long-horizon autonomy without oversight (agents drift, supervise accordingly), making decisions that require context it doesn’t have access to.

    The mental model I use: Claude is a thoughtful senior teammate who happens to be infinitely patient and always awake. That framing gets the relationship right. Over-rely on it and you get hurt. Under-rely on it and you’ve hired a senior teammate and asked them to run errands.


    The operational services: the things that do the work

    The third layer is the part most agency-AI writeups skip, because it’s unglamorous. It’s the set of operational services that do the actual deterministic work. Publishing. Research. Deployment. Monitoring. The stuff that shouldn’t require judgment once you’ve set it up correctly.

    I’m going to describe the shape without naming specific tools, because the shape is what’s durable and the specific tools will change.

    Publishers — services that take content prepared upstream and push it to the properties where it needs to live. WordPress for editorial content, social media scheduling for distribution, email tools for outbound. The publisher’s job is to execute reliably and log honestly. When it fails, it fails loudly enough that I notice.

    Research infrastructure — services that pull structured data about keywords, competitors, search volumes, backlink profiles, and so on. This is where AI-native agencies diverge most sharply from traditional ones. Traditional agencies do research manually. AI-native agencies run research as a pipeline: the structured data comes in, gets processed, and lands in the workspace as briefs and intelligence reports that the human and the AI both read.

    Background pipelines — the scheduled services that keep the workspace fresh. New briefs get generated. Stale content gets flagged. Traffic data gets ingested. The kinds of things that an agency would traditionally ask a human to do on a weekly rhythm, running autonomously in the background.

    Deployment and monitoring — how the technical side ships. Version control holds the source of truth. Deployments run on triggers. When something breaks, it breaks to a channel I actually read.

    The principle that holds all of this together: deterministic work belongs in deterministic systems. Don’t use an AI agent to do something a script can do. An AI agent adds judgment, which is valuable when you need judgment, and costly when you don’t. The operational services do the work that has a right answer every time. The AI handles the work that requires judgment.

    Most agency-AI failures I’ve watched happen are cases where someone tried to use an AI agent for the deterministic work. The agent mostly succeeds, occasionally hallucinates, and introduces a class of silent failure that didn’t exist in the deterministic version. It feels like you’re being clever. You’re introducing unreliability.


    The one human in the chair

    This is the part the vendor writeups never include, and it’s the most important piece.

    There is one human in the operator chair. That human is non-optional. Every workflow, every agent, every pipeline eventually terminates at a human decision or a human review gate. The AI stack does not run the business. The AI stack is a lever that makes one human capable of running what used to take many.

    What the human does in this configuration is different from what they would have done in a traditional agency. The human is not writing every post. The human is not doing every bit of research. The human is not executing every workflow. The human is:

    Setting the posture. What are we working on this week? What’s the priority? What’s the theme? The AI is exceptional at executing against clarity. It is not exceptional at deciding what to be clear about.

    Reading the synthesis. The AI surfaces what matters. The human decides what to do about it. Every morning brief, every weekly review, every escalation flags lands in front of the human, who makes the call.

    Making the judgment calls. When a client needs a difficult conversation. When a strategy needs to change. When something the AI suggested is actually wrong. These are the moments the AI can’t be left alone with. The operator role is increasingly concentrated around exactly these moments.

    Holding the relationships. Clients don’t want to talk to an AI. They want to talk to a human who happens to be very well-supported by AI. The difference matters enormously in trust, tone, and staying power of the engagement.

    Maintaining the stack itself. The stack doesn’t maintain itself. Every week there are small adjustments, small rewirings, small improvements. The operator is also the architect of the operating company, and the architecture is a living thing.

    A person who thought they were buying “AI that runs my agency for me” is going to be disappointed. A person who understood they were buying “a lever that makes them ten times more effective at the parts of agency work that actually matter” is going to be delighted. The difference is what you think you’re getting.


    The daily rhythm (what it actually looks like)

    Let me describe a real working day in this stack, because the abstract description doesn’t convey what using it feels like.

    Morning. I open Notion. The Morning Brief Agent ran overnight; the top of today’s Daily page already has a three-paragraph synthesis of the state of the business, pulled from the active projects, the task database, yesterday’s run reports, and the overnight changes. I read it in ninety seconds. I know what’s on fire, what’s progressing, what’s waiting on me. The context tax that used to cost me the first hour of every day is already paid.

    Morning block. I work through the highest-leverage thing on the day’s priority list. If it’s strategic, I work through it in a Claude conversation with the Notion workspace wired in, because grounding the AI in real context produces dramatically better thinking than working in isolation. If it’s technical, I work in Claude Code, because the terminal version handles multi-step technical work better. Either way, I’m working with the AI as a thinking partner, not a tool I reach for occasionally.

    Mid-day. The triage agent has processed whatever landed in the inbox. I scan its decisions, override the ones I disagree with, and dispatch anything important into its real database. The escalation agent has flagged the three things that need my attention today. I make the calls. These are the moments the stack needs a human for — no amount of clever configuration replaces them.

    Afternoon block. Content operations. Research intelligence lands as structured data in the workspace. Briefs get drafted. I review them. Approved briefs flow to the publishing pipeline. The pipeline runs, logs back to the workspace, and I get notified of anything that failed. I don’t write every post. I write the ones where my voice specifically matters, and I review the rest. The ratio is maybe one in ten that I write from scratch these days.

    Evening. Five minutes of close. Anything that didn’t get done gets re-dated. Tomorrow’s priority list pre-stages. I close Notion. The overnight agents will handle the rhythms while I sleep.

    That’s the day. It is dramatically different from running a traditional agency, and dramatically more sustainable. The cognitive load is substantially lower even while the operational throughput is substantially higher. That’s the whole promise of the pattern, and it’s the part that’s real.


    What this stack actually costs (and doesn’t)

    The direct tool costs for the stack in April 2026, at the level I run it:

    • Notion Business plan with AI add-on
    • Claude subscription (Max tier for the agent budget)
    • A cloud provider account for the operational services (running pennies to small dollars per day at my volume)
    • A handful of research and analysis tool subscriptions
    • Domain, email, and the usual small-business infrastructure

    Total monthly direct tool cost is the equivalent of what a traditional agency would spend on a single junior employee’s salary for one week. The leverage ratio is extreme, and it will get more extreme.

    What it costs that isn’t money:

    • Setup time. Weeks to stand up the initial version, months to iterate it into something that runs smoothly. This is not a weekend project.
    • Ongoing attention to the stack itself. Maybe ten percent of my week is spent on the operating company rather than on client work. That ratio is load-bearing; if I let it go below that, the stack rots.
    • Discipline about not adding cleverness. Every new tool, every new agent, every new integration is a tax on the coherence of the system. Most weeks I’m resisting the urge to add something, not looking for something to add.
    • Loneliness of the role. One-human agencies are lonely. You don’t have a team meeting. You don’t have a coffee conversation with a coworker. The stack is not a substitute for colleagues. This is the part nobody writes about and it’s genuinely significant.

    What this stack is not good for

    If I’m being honest about who should not run this pattern, it includes:

    Agencies that want to scale headcount. This stack is designed to make one human capable of more. It’s not designed to coordinate ten humans. A ten-person agency on this stack would have chaos problems I haven’t solved.

    Businesses where the work is primarily relational. Sales-heavy businesses, high-touch consulting, therapy practices. The stack is strong at operational and production work. It is weak at anything where the work is fundamentally “I am present with this other person.”

    Anyone uncomfortable with AI making meaningful decisions. The stack assumes you’re willing to let AI make decisions that have real consequences — triage, synthesis, drafting under your name. If that crosses your line philosophically, don’t force it. The stack won’t be fun for you.

    People looking for a plug-and-play system. This is a living architecture. It requires ongoing maintenance. It never stops being built. If you want something that works out of the box and stays working, buy software; don’t build an operating company.

    Early-stage businesses without a clear shape yet. The stack rewards clarity about what your business is. If you’re still figuring that out, the stack will accelerate whatever direction you’re going — which is great if the direction is right and brutal if it isn’t. Figure out the direction first, then build the stack.


    Who this stack is good for

    The operators I’ve seen get the most out of this pattern share a specific profile:

    • Running businesses with high operational complexity but small team size. Multi-property content operations, advisory practices, specialist agencies. The kind of business where one capable person with leverage beats a team without it.
    • Comfortable with systems thinking. The stack rewards people who think in terms of flows, interfaces, and substrates. If that vocabulary feels alien, the stack will feel alien.
    • Honest about what they’re good at and what they aren’t. The stack amplifies the operator. If the operator is strong at strategy and weak at execution, the stack handles the execution. If the operator is strong at execution and weak at strategy, the stack does not magically produce strategy. Know which version you are.
    • Willing to maintain the architecture. The stack is a long commitment to the operating company, not a one-time setup. Operators who enjoy tending the system do well. Operators who resent tending the system should not run it.

    If you recognize yourself in the good-fit list and not the bad-fit list, this pattern is probably worth the investment. If you’re on the fence, it probably isn’t yet — come back when the decision is clearer.


    The part I want to be brave about

    Here’s the part this article is supposed to be honest about.

    This pattern works for me. It might not work for you. The vendor-shaped narrative says every business should be AI-native, every agency should be running this stack, every operator should be ten times leveraged. That narrative is wrong. It’s wrong in the boring, everyday way that industry narratives are always wrong: it oversells, it under-discloses the costs, and it creates an expectation gap that a lot of operators are going to run into eighteen months from now.

    The accurate narrative is this: for a specific kind of operator running a specific kind of business, this stack produces a kind of leverage that was not previously available. For everyone else, it’s a distraction from what they should actually be doing, which is the hard work of their specific business with the tools that fit their specific situation.

    I am describing what I run because I think honest examples are more useful than vague generalities. I am not recommending you run it. I am recommending you look at your actual business, your actual operating constraints, and your actual relationship with AI tools, and decide whether a version of this pattern — adapted, simplified, or rejected — makes sense for you.

    There’s a version of this article that promises that if you copy my stack, you’ll get my outcomes. That article is lying to you. The outcomes come from matching the stack to the business, not from the stack itself.

    If you read this and it resonates, take the pieces that apply. If you read this and it doesn’t, take what you learned about what’s possible and leave the rest. Either response is correct.


    The five things I’d tell someone thinking about building something like this

    Start with the Control Center, not the agents. The Control Center is the anchor everything else builds against. If you build agents before you have the Control Center, the agents have nothing to write to. Build the workspace shape first. The rest follows.

    Resist the urge to add complexity. The operators who succeed with this pattern run simpler versions than they could. The operators who fail run more elaborate versions than they need. Every piece of the stack should be earning its place every week.

    Write everything down as you go. The operating company is a living architecture. Six months from now you will have forgotten why you made a specific configuration choice. Document the choices in the workspace as you make them. Future-you will thank present-you.

    Don’t over-trust the AI. It’s a teammate, not an oracle. It’s wrong sometimes. It’s confident when it shouldn’t be sometimes. Build review gates. Assume failure. The stack is resilient when you don’t assume otherwise.

    Accept that you are building an operating company, not deploying software. This is a long game. It doesn’t work in the first week. It starts working in the second month. It starts compounding in the sixth month. If you’re not willing to tend it for that long, don’t start.


    A closing observation

    I’ve been running variations of this stack for long enough to have opinions that don’t match what I thought I believed when I started. The biggest surprise has been how much of the work is operational hygiene rather than AI cleverness. Building an agent was the easy part. Running an agency on the operating company pattern has mostly been a discipline problem — staying consistent about metadata, about documentation, about review gates, about when to let the AI decide and when to intervene.

    The AI is not the interesting part anymore. The interesting part is the operating model the AI makes possible. That’s the part this article has tried to describe honestly, and that’s the part worth thinking about if you’re considering something similar.

    If you do build a version of this, I’d genuinely like to hear how it turns out. The frontier here is being figured out by operators sharing what works and doesn’t, and every honest report makes the next person’s build better. This is my report. I hope it helps.


    FAQ

    Can I run this stack solo? Yes. The stack is explicitly designed for solo operators or very small teams. One-human operation is the whole point. Multi-person teams work too but introduce coordination complexity the pattern doesn’t directly solve.

    How long does it take to build? The minimum viable version — Control Center, a handful of databases, one Custom Agent, Claude wired in — is a week of part-time work. The version that actually earns its place takes two to three months of iteration. It never stops getting built; it compounds over time.

    Do I need to know how to code? For the minimum viable version, no. Notion + Claude + Notion Custom Agents gets you a long way without writing code. For the operational services layer, some technical comfort is needed or you’ll need a technical collaborator. Claude Code dramatically lowers the bar here.

    What if Notion gets replaced by a competitor? The pattern survives. The Control Center, the database spine, the metadata discipline, the workspace-as-control-plane posture — all of those port to any capable workspace tool. If something displaces Notion in 2027, the migration is real work but the operating model is durable. The durable asset is the pattern, not the specific tool.

    What if Claude gets replaced by a competitor? Also fine. The pattern assumes there’s an intelligence layer wired into the workspace; Claude is the current implementation of that layer. If another frontier model becomes more suitable, swap it. The MCP standard that connects everything is model-agnostic. This is deliberate.

    Can I use ChatGPT or another AI instead of Claude? Mostly yes. The MCP-to-Notion pattern works with any AI that supports MCP, including ChatGPT, Cursor, and others. I use Claude for the reasons described above, but the stack pattern is compatible with other frontier models. Don’t let tool preferences get in the way of the architecture.

    How much does this cost to run? The tool subscription stack costs roughly what one junior employee’s weekly salary would cost per month, total. The non-monetary costs (setup time, maintenance attention, lifestyle tradeoffs of solo operation) are more significant and worth thinking about before committing.

    Is this sustainable for a growing business? Yes, up to a point. The pattern scales smoothly to a certain operational volume per human. Beyond that, you need more humans, and coordinating multiple humans on this stack introduces problems that the solo version doesn’t have. Most operators hit the natural ceiling before they hit the growth limit.


    Sources and further reading

    Related reading from the broader ecosystem:

  • How to Wire Claude Into Your Notion Workspace (Without Giving It the Keys to Everything)

    How to Wire Claude Into Your Notion Workspace (Without Giving It the Keys to Everything)

    Last refreshed: May 15, 2026

    Update — May 15, 2026: On May 13, 2026, Notion shipped the Notion Developer Platform (version 3.5), with Claude as a launch partner. The platform adds Workers, database sync, an External Agents API, and a Notion CLI. The patterns described in this article still work, but there is now a native, sanctioned alternative for some of what previously required custom MCP wiring or third-party automation. For the full breakdown of what changed and what it means for the Notion + Claude stack, see Notion Developer Platform Launch (May 13, 2026). For the underlying operating philosophy, see The Three-Legged Stack.

    The step most tutorials skip is the one that actually matters.

    Every guide to connecting Claude to Notion walks you through the same mechanical sequence — OAuth flow, authentication, running claude mcp add, and done. It works. The connection lights up, Claude can read your pages, write to your databases, and suddenly your AI has the run of your workspace. The tutorials stop there and congratulate you.

    Here’s the part they don’t mention: according to Notion’s own documentation, MCP tools act with your full Notion permissions — they can access everything you can access. Not the pages you meant to share. Everything. Every client folder. Every private note. Every credential you ever pasted into a page. Every weird thing you wrote about a coworker in 2022 and forgot was there.

    In most setups the blast radius is enormous, the visibility is low, and the decision to lock it down happens after something goes wrong instead of before.

    This is the guide that takes the extra hour. Wiring Claude into your Notion workspace is straightforward. Wiring Claude into your Notion workspace without giving it the keys to everything takes a few additional decisions, a handful of specific configuration choices, and a mental model for what should and shouldn’t flow across the connection. That’s the hour worth spending.

    I run this setup across a real production workspace with dozens of active properties, real client work, and data I genuinely don’t want an AI to have unbounded access to. The pattern below is what works. It is also honest about what doesn’t.


    Why Notion + Claude is worth doing carefully

    Before the mechanics, it’s worth being clear about what you get when you wire this up correctly.

    Claude with access to Notion is not Claude with a better search function. It is a Claude that can read the state of your business — briefs, decisions, project status, open loops — and reason across them to help you run the operation. It can draft follow-ups to conversations it finds in your notes. It can pull together summaries across projects. It can take a decision you’re weighing, find every related piece of context in the workspace, and give you a grounded opinion instead of a generic one.

    That’s the version most operator-grade users want. And it’s only valuable if the trust boundary is drawn correctly. A Claude that has access to your relevant context is a superpower. A Claude that has access to everything you’ve ever written is a liability waiting to catch up with you.

    The whole article is about drawing that boundary on purpose.


    The two connection options (and which one you actually want)

    There are two ways to connect Claude to Notion in April 2026, and the right one depends on what you’re doing.

    Option 1: Remote MCP (Notion’s hosted server). You connect Claude — whether that’s Claude Desktop, Claude Code, or Claude.ai — to Notion’s hosted MCP endpoint at https://mcp.notion.com/mcp. You authenticate through OAuth, which opens a browser window, you approve the connection, and it’s live. Claude can now read from and write to your workspace based on your access and permissions.

    This is the officially-supported path. Notion’s own documentation explicitly calls remote MCP the preferred option, and the older open-source local server package is being deprecated in favor of it. For most operators, this is the right answer.

    Option 2: Local MCP (the legacy / open-source package). You install @notionhq/notion-mcp-server locally via npm, create an internal Notion integration to get an API token, and configure Claude to talk to the local server with your token. You then have to manually share each Notion page with the integration one by one — the integration only sees pages you explicitly grant access to.

    This path is more work and is being phased out. But there’s one genuine reason to still use it: the local path uses a token and the remote path uses OAuth, which means the local path works for headless automation where a human isn’t around to click OAuth buttons. Notion MCP requires user-based OAuth authentication and does not support bearer token authentication. This means a user must complete the OAuth flow to authorize access, which may not be suitable for fully automated workflows.

    For 95% of setups, remote MCP is the right answer. For the 5% running true headless agents, the local package is still the pragmatic choice even though it’s on its way out.

    The rest of this guide assumes remote MCP. I’ll flag the places the advice differs for local.


    The quiet part Notion tells you out loud

    Before we get to the setup, one more thing you need to internalize because it shapes every decision below.

    From Notion’s own help center: MCP tools act with your full Notion permissions — they can access everything you can access.

    Read that sentence twice.

    If you are a workspace member with access to 140 pages across 12 databases, your Claude connection can access 140 pages across 12 databases. Not the 15 you’re working on today. All of them. OAuth doesn’t scope you down to “this project.” It says yes or no to “can Claude see your workspace.”

    This is fine when your workspace is already organized the way you’d want an AI to see it. It is catastrophic when it isn’t, because most workspaces have accumulated years of drift, private notes, credential-adjacent content, sensitive client data, and old experiments that nobody bothered to clean up.

    So before you connect anything, you do the workspace audit. Not because Notion says so. Because your future self will thank you.


    The pre-connection audit (the step tutorials skip)

    Fifteen minutes with the workspace, before you click the OAuth button. Here’s the checklist I run through:

    Find anything that looks like a credential. Search your workspace for the words: password, API key, token, secret, bearer, private key, credentials. Read the results. Move anything sensitive to a credential manager (1Password, Bitwarden, a password-protected vault — not Notion). Delete the Notion copies.

    Find anything you wouldn’t want an AI to read. Search for: divorce, legal, lawsuit, personal, venting, complaint, therapist. Yes, really. People put things in Notion they’ve forgotten are in Notion. An AI that has access to everything you can access will find those things and occasionally surface them in responses. This is embarrassing at best and career-ending at worst.

    Look at your database of clients or contacts. Is there anything in there that shouldn’t travel through an AI provider’s servers? Notion processes MCP requests through Notion’s infrastructure, not yours. Sensitive legal matters, medical information, financial details about third parties — these may deserve a workspace or sub-page that stays outside of what Claude is allowed to see.

    Identify what Claude actually needs. Make a short list: your active projects, your working databases, your briefs page, your daily/weekly notes. This is what you actually want Claude to have context on. The rest is noise.

    Decide your posture. Two options here. You can run Claude against your main workspace and accept the blast radius, or you can create a separate workspace (or a teamspace) that contains only the pages and databases you want Claude to see, and connect Claude to that one. The second option is more work upfront. It is also the only version that actually draws the boundary.

    I run the second option. My Claude-facing workspace is genuinely a subset of what I work with, and the rest of my Notion is on a different membership. It took an hour to set up. It was worth it.


    Connecting remote MCP to Claude Desktop

    Now the mechanics. Starting with Claude Desktop because it’s the simplest.

    Claude Desktop gets Notion MCP through Settings → Connectors (not the older claude_desktop_config.json file, which is being phased out for remote MCP). This is available on Pro, Max, Team, and Enterprise plans.

    Open Claude Desktop. Settings → Connectors. Find Notion (or add a custom MCP server with the URL https://mcp.notion.com/mcp). Click Connect. A browser window opens, Notion asks you to authenticate, you approve. Done.

    The connection now lives in your Claude Desktop. You can start a new conversation and ask Claude to read a specific page, summarize a database, or draft something based on workspace content, and it will.

    One hygiene note: Claude Desktop connections are per-account. If you have multiple Claude accounts (say, a personal Pro and a work Max), each one needs its own connection to Notion. The good news is you can point each one at a different Notion workspace — personal Claude at personal Notion, work Claude at work Notion. This is the operator pattern I recommend for anyone running more than one business context through Claude.


    Connecting remote MCP to Claude Code

    Claude Code is the path most operators actually run at depth, because it’s the version of Claude that lives in your terminal and can compose MCP calls into real workflows.

    The command is one line:

    claude mcp add --transport http notion https://mcp.notion.com/mcp

    Need this set up for your team?

    I set up Claude integrations, GCP infrastructure, and AI workflows for businesses. If you’d rather ship than configure — will@tygartmedia.com

    Then authenticate by running /mcp inside Claude Code and following the OAuth flow. Browser opens, Notion asks you to authorize, you approve, and the connection is live.

    A few options worth knowing about at setup time:

    Scope. The --scope flag controls who gets access to the MCP server on your machine. Three options: local (default, just you in the current project), project (shared with your team via a .mcp.json file), and user (available to you across all projects). For Notion, user scope is usually right — you’ll want Claude to reach Notion from any project you’re working in, not just the current one.

    The richer integration. Notion also ships a plugin for Claude Code that bundles the MCP server along with pre-built Skills and slash commands for common Notion workflows. If you’re doing this seriously, install the plugin. It adds commands like generating briefs from templates and opening pages by name, and saves you from writing your own.

    Checking what’s connected. Inside Claude Code, /mcp lists every MCP server you’ve configured. /context tells you how many tokens each one is consuming in your current session. For Notion specifically, this is useful because MCP servers have non-zero context cost even when you’re not actively using them — every tool exposed by the server sits in Claude’s context, eating tokens. Running /context occasionally is how you notice when an MCP connection is heavier than you expected.


    The permissions pattern that actually protects you

    Now we’re past the mechanics and into the hygiene layer — the part that most guides don’t cover.

    Once Claude is connected to your Notion workspace, there are three specific configuration moves worth making. None of them are hard. All of them pay rent.

    1. Scope the workspace, don’t scope the connection

    The OAuth connection doesn’t let you say “Claude can see these pages but not those.” It lets you say “Claude can see this workspace.” So the place to draw the boundary is at the workspace level, not at the connection level.

    If you have sensitive content in your main workspace, move it. Create a separate workspace for Claude-facing content and keep the sensitive stuff out. Or use Notion’s teamspace feature (Business and Enterprise) to isolate access at the teamspace level.

    This feels like over-engineering until the first time Claude surfaces something in a response that you had forgotten was in your workspace. After that, it doesn’t feel like over-engineering.

    2. For Enterprise: turn on MCP Governance

    If you’re on the Enterprise plan, there’s an admin-level control worth enabling even if you trust your team. From Notion’s docs: with MCP Governance, Enterprise admins can approve specific AI tools and MCP clients that can connect to Notion MCP — for example Cursor, Claude, or ChatGPT. The approved-list pattern is opt-in: Settings → Connections → Permissions tab, set “Restrict AI tools members can connect to” to “Only from approved list.”

    Even if you only approve Claude today, the control gives you the ability to see every AI tool anyone on your team has connected, and to disconnect everything at once with the “Disconnect All Users” button if you ever need to. That’s the kind of control you want to have configured before you need it, not after.

    3. For local MCP: use a read-only integration token

    If you’re using the local path (the open-source @notionhq/notion-mcp-server), you have more granular control than the remote path gives you. Specifically: when you create the integration in Notion’s developer settings, you can set it to “Read content” only — no write access, no comment access, nothing but reads.

    A read-only integration is the right default for anything exploratory. If you want Claude to be able to write too, enable write access later when you’ve decided you trust the specific workflow. Don’t give write access by default just because the integration setup screen presents it as an option.

    This is the one place the local path is actually stronger than remote — you can shape the integration’s capabilities before you grant it access, and the integration only sees the specific pages you share with it. For high-sensitivity setups, this granularity is worth the tradeoff of running the legacy package.


    Prompt injection: the risk nobody wants to talk about

    One more thing before we leave the hygiene section. It’s the thing the industry is least comfortable being direct about.

    When Claude has access to your Notion workspace, Claude also reads whatever is in your Notion workspace. Including pages that came from outside. Including meeting notes that were imported from a transcript service. Including documents shared with you by clients. Including anything you pasted from the web.

    Every one of those is a potential vector for prompt injection — hidden instructions buried in content that, when Claude reads the content, hijack what Claude does next.

    This is not theoretical. Anthropic itself flags prompt injection risk in the MCP documentation: be especially careful when using MCP servers that could fetch untrusted content, as these can expose you to prompt injection risk. Notion has shipped detection for hidden instructions in uploaded files and flags suspicious links for user approval, but the attack surface is larger than any detection system can fully cover.

    The practical operator response is three-part:

    Don’t give Claude access to content you didn’t write, without reading it first. If a client sends you a document and you paste it into Notion and Claude has access to that database, you have effectively given Claude the ability to be instructed by your client’s document. This might be fine. It might be a problem. Read the document before it goes into a Claude-accessible location.

    Be suspicious of workflows that chain untrusted content into actions. A workflow where Claude reads a web-scraped summary and then uses that summary to decide which database row to update is a prompt injection target. If the scraped content can shape Claude’s action, the scraped content can be weaponized.

    Use write protections for anything consequential. Anything where the cost of Claude doing the wrong thing is real — sending an email, deleting a record, updating a client-facing page — belongs behind a human-approval gate. Claude Code supports “Always Ask” behavior per-tool; use it for writes.

    This sounds paranoid. It’s not paranoid. It’s the appropriate level of caution for a class of attack that is genuinely live and that the industry has not yet figured out how to fully defend against.


    What this actually enables (the payoff section)

    Once you’ve done the setup and the hygiene work, here’s what you now have.

    You can sit down at Claude and ask it questions that require real workspace context. What’s the status of the three projects I touched last week? Pull together everything we’ve decided about pricing across the client work this quarter. Draft a response to this incoming email using context from our ongoing conversation with this client. Claude reads the relevant pages, synthesizes across them, and responds with actual grounding — not a generic answer shaped by whatever prompt you happen to type.

    You can run Claude Code against your workspace for development-adjacent operations. Generate a technical spec from our product page notes. Create release notes from the changelog and feature pages. Find every page where we’ve documented this API endpoint and reconcile the inconsistencies.

    You can set up workflows that flow across tools. Claude reads from Notion, acts on another system via a different MCP server, writes results back to Notion. This is the agentic pattern the industry keeps talking about — and with the right permissions hygiene, it actually becomes usable instead of scary.

    None of this is theoretical. I use this pattern every working day. The value is real. The hygiene discipline is what keeps the value from turning into a liability.


    When this setup goes wrong (troubleshooting honestly)

    Five failure modes I’ve seen, in order of frequency.

    Claude doesn’t see the page you asked about. For remote MCP, this almost always means the page is in a workspace you’re not a member of, or in a teamspace you don’t have access to. For local MCP, it means the integration hasn’t been granted access to that specific page — you have to go to the page, click the three-dot menu, and add the integration manually.

    OAuth flow doesn’t complete. Usually a browser issue — popup blocker, wrong Notion account signed in, session expired. Clear auth, try again. If Claude Desktop, disconnect the connector entirely and re-add.

    The connection succeeds but Claude doesn’t seem to be using it. Run /mcp in Claude Code to verify the server is listed and connected. If it’s there and Claude still isn’t invoking it, the issue is usually in how you’re asking — Claude won’t reach for MCP tools just because they exist; you need to phrase the request in a way that makes it obvious the tool is relevant. Find the page about X in Notion works better than tell me about X.

    MCP server crashes or returns errors. For remote, this is rare and usually resolves itself — Notion’s hosted server has the standard cloud-reliability profile. For local, check your Node version (the server requires Node 18 or later), your config file syntax (JSON is unforgiving about trailing commas), and your token format.

    Context token budget goes through the roof. Every MCP server in your connected list contributes tools to Claude’s context on every request. If you have five MCP servers configured, that’s five sets of tool descriptions being loaded into every conversation. Run /context in Claude Code to see the cost. If it’s painful, disconnect the servers you’re not actively using.


    The mental model that keeps you sane

    Here’s the mental model I use for the whole setup. It’s short.

    Claude plus Notion is like giving a new, very capable employee access to your business. You wouldn’t hand a new hire every password, every file, every client record, every private note on day one. You’d give them access to the specific things they need to do the job, watch how they use that access, and expand trust over time based on track record.

    The MCP connection works exactly that way. You decide what Claude gets to see. You decide what Claude gets to write. You watch how it uses that access. You expand the boundary as trust earns itself.

    The operators who get hurt by this kind of setup are the ones who skip the first step and give Claude everything on day one. The operators who get the real value out of it are the ones who treat the connection the way they’d treat any other employee — with deliberate scope, real oversight, and the willingness to revoke access if something goes wrong.

    That’s the discipline. That’s the whole thing.


    FAQ

    Do I need to install anything to connect Claude to Notion? For remote MCP (the recommended path), no installation is required — you connect via OAuth through Claude Desktop’s Settings → Connectors or Claude Code’s claude mcp add command. For local MCP (legacy), you install @notionhq/notion-mcp-server via npm and create an internal Notion integration.

    What’s the URL for Notion’s remote MCP server? https://mcp.notion.com/mcp. Use HTTP transport (not the deprecated SSE transport).

    Can Claude see my entire Notion workspace by default? Yes. MCP tools act with your full Notion permissions — they can access everything you can access. The boundary is set by your workspace membership and teamspace access, not by the MCP connection itself. If you need finer-grained control, isolate Claude-facing content into a separate workspace or teamspace.

    Can I use Notion MCP with automated, headless agents? Remote Notion MCP requires OAuth authentication and doesn’t support bearer tokens, which makes it unsuitable for fully automated or headless workflows. For those cases, the legacy @notionhq/notion-mcp-server with an API token still works, but it’s being phased out.

    What plans support Notion MCP? Notion MCP works with all plans for connecting AI tools via MCP. Enterprise plans get admin-level MCP Governance controls (approved AI tool list, disconnect-all). Claude Desktop MCP connectors are available on Pro, Max, Team, and Enterprise plans.

    Can my company’s admins control which AI tools connect to our Notion workspace? Yes, on the Enterprise plan. Admins can restrict AI tool connections to an approved list through Settings → Connections → Permissions tab. Only admin-approved tools can connect.

    Is Notion MCP secure for confidential business data? The MCP protocol itself respects Notion’s permissions — it can’t bypass what you have access to. However, content flowing through MCP is processed by the AI tool you’ve connected (Claude, ChatGPT, etc.), which has its own data handling policies. For highly sensitive content, the right move is to isolate it in a workspace that Claude doesn’t have access to, rather than relying on the protocol alone to contain it.

    What about prompt injection attacks through Notion content? Real risk. Anthropic explicitly flags it in their MCP documentation. Notion has shipped detection for hidden instructions and flags suspicious links, but no detection system catches everything. The operator response: don’t give Claude access to content you didn’t write without reviewing it first, be suspicious of workflows where untrusted content shapes Claude’s actions, and put human-approval gates on anything consequential.

    What’s the difference between Notion’s built-in AI and connecting Claude via MCP? Notion’s built-in AI (Notion Agent and Custom Agents) runs inside Notion and uses Notion’s integration with frontier models. Connecting Claude via MCP brings Claude — your chosen model, in your chosen interface, with its full capability — to your workspace as an external client. The built-in option is simpler; the MCP option is more powerful and composable across other tools.


    Closing note

    Most tutorials treat the connection as the goal. The connection is the easy part. The hygiene is the part that matters.

    If you wire Claude into your Notion workspace thoughtlessly, you’ve given a capable AI access to every corner of your operational history, and you’ll be surprised how much of what’s in there you’d forgotten. If you wire it in deliberately — with a scoped workspace, with the permissions you’ve thought about, with the posture of giving a new employee measured access — you’ve built something that pays rent every day without ever becoming the liability it could have been.

    One hour of setup. One hour of cleanup. And then one of the most useful AI configurations currently possible in April 2026.

    The intersection of Notion and Claude is where the operator work actually happens now. Worth setting up right.


    Sources and further reading

  • The Soda Machine Thesis: A Mental Model for Running an AI-Native Business on Notion

    The Soda Machine Thesis: A Mental Model for Running an AI-Native Business on Notion

    The hardest part of running an AI-native business on Notion in 2026 isn’t the tools. The tools are fine. The tools ship regularly and they work. The hard part is that the vocabulary hasn’t caught up with the reality, and when the vocabulary is wrong, your design choices get wrong too.

    Here’s what I mean. When I started seriously composing Workers, Agents, and Triggers in Notion, I found I was making the same kinds of mistakes over and over. Building a worker for something an agent could have handled with good instructions. Attaching five tools to an agent that only needed two. Setting up a scheduled trigger for something that should have fired on an event. After the third or fourth time, I realized the mistakes had a common source: I didn’t have a mental model for when to reach for which piece.

    Notion doesn’t give you one. The documentation is accurate but it’s a list of capabilities. Vendor-shaped — here is what Custom Agents can do, here is what Workers do, here are your trigger types. All true. All useless for the question I actually had, which was given a job I want done, which piece do I build?

    So I made a mental model. It’s imperfect and it’s mine, but it has survived a few months of real use and it has saved me from a dozen architecture mistakes I would have otherwise made. This article is the model.

    I call it the Soda Machine Thesis. It might sound silly. It works.


    The core analogy

    Workers are syrups. Agents are soda fountain machines. Triggers are how the machine dispenses.

    When someone asks for a custom soda fountain — a Custom Agent — three decisions get made, in order:

    1. Which syrups (workers and tools) load into this machine? What capabilities does it need access to? What external services does it need to reach? What deterministic operations does it need to perform?
    1. How is the machine programmed? What are its instructions? What’s its job description? How does it think about what it’s doing? (This is the part where agents diverge most — two machines with identical syrups behave completely differently based on instructions.)
    1. How does it dispense? Does it pour when someone presses a button (manual trigger)? Does it pour on a schedule (timer)? Does it pour when the environment changes — a page gets created, a status flips, a comment gets added (event sensor)?

    That’s the whole model. Three questions, in that order. If you can answer all three cleanly, you have a working agent. If you can’t answer one of them, you have an agent that is going to produce noise and frustrate you.

    I have watched this analogy clarify a dozen conversations that were going nowhere. “I want an agent that…” — and then I ask the three questions, and halfway through the answers it becomes obvious what the person actually wants is a simpler thing. Sometimes they don’t need an agent at all, they need a template with a database automation. Sometimes they need a worker, not an agent. Sometimes they need an agent with zero workers and better instructions.

    The analogy does real work. That’s the whole point of a mental model.


    Where the analogy holds

    The map is cleaner than you’d expect.

    Workers are syrups. Stateless, parameterized, reusable. The same worker — fetch-url, summarize, post-to-channel, whatever — can power a dozen agents. You build it once, you use it everywhere. A worker that sends an email works the same way whether it’s being called by a triage agent, a brief-writer, or a customer-response agent. That’s what syrup means: the ingredient doesn’t care which drink it’s going into.

    Agents are machines. They select, sequence, and orchestrate. An agent knows when to reach for which worker. An agent knows what the job is and reasons about how to do it. An agent can read a database, synthesize what it finds, reach for a tool to do a specific deterministic step, synthesize again, and return a result. An agent is a little piece of judgment on top of a set of capabilities.

    Triggers are how the machine dispenses. This is the cleanest part of the map because Notion’s own trigger types map almost 1:1 onto the analogy:

    • Button press or @mention → manual dispatch (“I’m pressing the button for a Coke”)
    • Schedule → timer (“pour me a drink at 7am every day”)
    • Database event → sensor (“someone just put a cup under the dispenser; fill it”)

    You don’t need to memorize trigger type names. You need to ask “how should this machine know it’s time to pour?” Once you know the answer, the trigger type follows.


    Where the analogy leaks (and what to do about it)

    No analogy is perfect. This one has four honest leaks that are worth knowing before you rely on the model.

    1. Agents have native hands, not just syrups

    A Custom Agent can read pages, search the workspace, write to databases, and send notifications without a single worker attached. Workers are specialty syrups for the things the base machine can’t do natively — external APIs, deterministic writes to strict database schemas, code execution, anything requiring exact outputs every time.

    This means not every agent needs workers. In fact, my highest-leverage agents often have zero workers. They use the base machine’s native capabilities, combined with strong instructions, to do the job.

    The practical consequence: don’t reach for a worker reflexively. Start by asking what the agent can do with just its native hands and good instructions. Only add workers when the agent genuinely needs capability it doesn’t have.

    2. Machine programming matters as much as syrup selection

    The instructions you give an agent — its system prompt, its job description, its operating rules — are doing as much work as the workers you attach. Two agents with identical workers will behave completely differently based on how they’re instructed.

    People tend to under-invest here. They attach five workers, write three sentences of instruction, and wonder why the agent is flaky. The fix is not more workers. The fix is writing instructions the way you’d write onboarding docs for a new employee — specific, scoped, honest about edge cases, clear about what the agent should do when it’s uncertain.

    My rule: if I’m about to attach a worker because the agent “keeps getting it wrong,” I first check whether better instructions would fix the problem. Nine times out of ten they would.

    3. Workers aren’t a single thing

    This is the leak that surprised me when I learned it. There are actually three kinds of worker, and they behave differently:

    • Tools — on-demand capabilities. The classic syrup. An agent calls them when it needs them. Example: a worker that fetches a URL and returns the text.
    • Syncs — background data pipelines that run on a schedule and write to a database. Not dispensed by an agent. These are more like an ice maker — they run on the infrastructure, filling the building up, and the machines use what the ice maker produces.
    • Automations — event handlers that fire when something happens in the workspace. Like a building’s fire suppression — nobody’s pressing a button; the environment triggers it.

    This matters because syncs and automations don’t need an agent to dispatch them. They run autonomously. If you’re building something that feeds a database on a schedule, that’s a sync, not a tool, and it doesn’t need an agent. If you’re building something that reacts to a page being updated, that’s an automation, not a tool.

    Getting this wrong is one of the most common architecture mistakes. People build an agent to dispatch a sync because they think everything has to flow through an agent. It doesn’t. Let the infrastructure do the infrastructure’s job.

    4. Determinism vs. judgment is the design axis

    The thing the soda analogy doesn’t capture well is that workers and agents are not just interchangeable building blocks. They serve fundamentally different purposes:

    • Workers shine when you want deterministic behavior. Same input, same output, every time. Schema-strict writes. External API calls where the shape of the request and response are fixed.
    • Agents shine when you want judgment, composition, and natural-language reasoning. Variable inputs. Fuzzy requirements. Synthesis across multiple sources.

    The red flag: building a worker for something an agent could do reliably with good instructions. You’re over-engineering.

    The green flag: an agent keeps being flaky at a specific operation. Harden that operation into a worker. Now the agent handles the judgment part, and the worker handles the reliable part.


    The “should this be a worker?” test

    When I’m trying to decide whether to build a worker or let an agent handle something, I run a five-point checklist. If two or more are true, build a worker. If fewer than two are true, stay manual or solve it with agent instructions.

    1. You’ve done the manual thing three or more times. The third time is the signal. First time is discovery, second time is coincidence, third time is a pattern worth capturing.
    2. The steps are stable. If you’re still figuring out how to do the thing, don’t codify it yet. You’ll codify the wrong version and have to rewrite.
    3. You need deterministic schema compliance. Writes that must fit a database schema exactly are worker territory. Agents can write to databases, but if the schema has strict requirements, a worker is more reliable.
    4. You’re calling an external service Notion can’t reach natively. This is often the clearest signal. If it’s outside Notion and needs to be reached programmatically, it’s a worker.
    5. The judgment required is minimal or already encoded in rules. If the decisions are simple enough to express as code, a worker is fine. If the decisions need real reasoning, it’s agent territory.

    This test is not a strict algorithm. It’s a gut-check that catches the most common over-engineering mistakes before they happen.


    The roles matter more than the technology

    Here’s the extension of the analogy that actually made the whole thing click for me.

    Every construction project has four roles. The Soda Machine Thesis as I originally described it has three of them. The one I hadn’t named — and the one you’re probably missing in your own workspace — is the Architect.

    Construction roleYour system
    Owner / DeveloperThe human in the chair. Commissions work, approves output, holds the keys.
    ArchitectThe AI-in-conversation. Claude, Notion Agent in chat, whatever model you’re actively designing with.
    General ContractorA Custom Agent running in production.
    SubcontractorA Worker. Called in for specialty work.

    The distinction that matters: the Architect and the General Contractor are the same technology, playing different roles. When you’re chatting with a model about how to design a system, that model is acting as Architect — designing the thing before it gets built. When a Custom Agent runs autonomously against your databases overnight, it’s acting as General Contractor — executing the design.

    Same underlying AI. Completely different role.

    Getting this distinction wrong is how operators end up either (a) over-trusting autonomous agents with design decisions they shouldn’t be making, or (b) under-using conversational AI for the system-design work it’s actually best at. Chat with the Architect. Deploy the GC. Don’t confuse them.


    Levels of automation (what you’re actually doing at each stage)

    Most operators cycle through these levels as they get deeper into the pattern. Knowing which level you’re currently at — and which level a specific problem actually needs — prevents a lot of wasted effort.

    Level 0: The Owner does it. You manually do the thing. This is fine. Everything starts here. Some things should stay here.

    Level 1: Handyman. You’ve built a template, a button, a saved view. No AI involvement. Native Notion helps you do it faster. Still you doing the work.

    Level 2: Standard Build. Notion’s native automations handle it. Database triggers fire on status changes. Templates get applied automatically. Still deterministic, still no AI.

    Level 3: Self-Performing GC. A Custom Agent does the work natively — reading and writing inside Notion, reasoning about context, no workers attached. This is where agents earn their keep for the first time.

    Level 4: GC + One Trade. An agent with one specialized worker. The agent handles judgment; the worker handles a single deterministic step. This is the most common production pattern.

    Level 5: Full Project Team. An agent orchestrating multiple workers in sequence. Real project coordination. A brief-writer agent that calls a URL-capture worker, then a summarization worker, then a publishing worker, all in order.

    Level 6: Program Management. Multiple agents coordinated by an overarching structure. One agent that dispatches to specialist agents. Portfolio-level orchestration. This is where it gets complicated and where most operators don’t need to go.

    The mistake I made early on, and watch other operators make, is jumping to Level 5 when Level 3 would have worked. More pieces means more failure points. Solve it at the lowest level that works.


    Governance: permits, inspections, and change orders

    The analogy extends further than I expected into governance — which is the unsexy part of running real agents in production, but it’s the part that separates operators who keep their agents working from operators whose agents quietly stop working without them noticing.

    • Pulling a permit = Attaching a worker to an agent. You’re granting that specialty trade permission to work on your job. This is not a nothing decision. Be deliberate.
    • Building inspection = Setting a worker tool to “Always Ask” mode. Before the work ships, the human reviews it. For any worker that does something consequential, this is the default.
    • Certificate of Occupancy = The moment a capability graduates from Building to Active status in your catalog. Before that moment, treat it as construction. After, treat it as load-bearing.
    • Change Order = Editing an agent’s instructions mid-project. The scope changed. Document it.
    • Punch List = The run report every worker should write on every execution — success and failure. No silent runs. If you can’t see what your agent did, you don’t know what it did.
    • Warranty work = Iterative fixes after a worker is deployed. v0.1 to v0.2 to v0.3. This never stops.

    The governance layer sounds boring but it’s what makes agents run for months instead of days. An agent without run reports eventually drifts, fails silently, and leaves you discovering the failure weeks later when the downstream thing it was supposed to do quietly stopped happening. The governance rituals — inspections, change orders, punch lists — are not overhead. They’re what makes the system durable.


    The revised one-sentence summary

    Putting it all together, here is the whole thesis in one sentence:

    Notion is the building. Databases are the floors. The Owner runs the project. Architects design in conversation. General Contractors (agents) execute on-site. Subcontractors (workers) run specialty trades. Syncs are maintenance contracts. Triggers are permits, sensors, and dispatch radios.

    If you can hold that sentence in your head, you can design automation in Notion without getting lost in the vocabulary. When you’re about to build something, ask: which role am I playing right now? Which role does this piece need to play? Who’s the Owner, who’s the Architect, who’s the GC, who’s the sub? If you can answer, the architecture writes itself.


    Practical takeaways

    If you made it this far, here are the five things I’d want you to walk away with:

    1. Not every agent needs workers. Start with native capabilities and strong instructions. Add workers only when the agent can’t do the thing otherwise.
    1. The third time is the signal. Don’t build infrastructure for something you’ve only done twice. You’ll build the wrong version. The third time is when the pattern has stabilized enough to capture.
    1. Syncs and automations don’t need an agent. If you’re feeding a database on a schedule, or reacting to a workspace event, let the infrastructure do it. Don’t wrap it in an agent for no reason.
    1. Separate the Architect from the GC. Use conversational AI to design the system. Use Custom Agents to run the system. Don’t let an autonomous agent make design decisions that should be made in conversation.
    1. Write run reports for everything. Silent success is worse than loud failure, because silent success is indistinguishable from silent failure until weeks later. Every agent, every worker, every run — writes a report somewhere readable.

    That’s the model. It is imperfect and it is mine. If you adopt it, make it your own. If you have a better one, I’d honestly like to hear about it.


    FAQ

    What’s the difference between a Notion Worker and a Custom Agent? A Worker is a coded capability — deterministic, reusable, typically written in TypeScript — that a Custom Agent can call. A Custom Agent is an autonomous AI teammate that lives in your workspace, has instructions, runs on triggers, and can optionally use Workers to do specialized tasks. Workers are capabilities. Agents are operators that can use those capabilities.

    Do I need Workers to use Custom Agents? No. Many Custom Agents run perfectly well with zero Workers attached, using only Notion’s native capabilities (reading pages, writing to databases, searching, sending notifications) plus well-written instructions. Workers become necessary when you need to reach external services or enforce strict deterministic behavior.

    What are the three trigger types for Custom Agents? Manual (button press, @mention, or direct invocation), scheduled (recurring on a timer), and event-based (a database page is created, updated, deleted, or commented on). Pick the one that matches how the agent should know it’s time to act.

    When should I build a Worker versus letting an Agent handle something? Build a Worker when at least two of these are true: you’ve done the manual thing three or more times, the steps are stable, you need deterministic schema compliance, you’re calling an external service Notion can’t reach, or the judgment required is minimal. If fewer than two are true, stay manual or solve it with agent instructions.

    What’s the difference between a Tool, a Sync, and an Automation? A Tool is an on-demand capability that an agent calls when needed. A Sync is a background pipeline that runs on a schedule and writes to a database — no agent required. An Automation is an event handler that fires when something changes in the workspace — also no agent required. Tools are dispatched by agents; syncs and automations run on the infrastructure.

    What’s the Architect/GC distinction? When you chat with AI to design a system, the AI is playing Architect — thinking about what should be built. When a Custom Agent runs autonomously in your workspace, it’s playing General Contractor — executing the design. Same technology, different role. Don’t confuse them: let Architects design, let GCs execute.

    Does this apply outside of Notion? The Soda Machine Thesis is written around Notion’s specific implementation of Workers, Agents, and Triggers, but the underlying pattern (deterministic capabilities + judgment layer + trigger mechanism) applies to most modern agent frameworks. The vocabulary may differ. The architecture is the same.


    Closing note

    Mental models earn their place by changing the decisions you make. If the Soda Machine Thesis changes how you decide what to build next in your Notion workspace, it has done its job. If it doesn’t, discard it and find one that does.

    The reason I wrote it down is that the vocabulary available for thinking about AI-native workspaces in 2026 is still mostly vendor vocabulary, and vendor vocabulary optimizes for describing what a product can do rather than helping operators make good choices. The operator vocabulary has to come from operators. This is mine, offered in that spirit.

    If you’re running this pattern and have refinements, they’re welcome. The thesis is a living document in my own workspace. It gets smarter every time someone pushes back.


    Sources and further reading

    This mental model builds on earlier conceptual work across multiple AI tools (Notion Agent, Claude, GPT) contributing to the same thesis over a series of architecture conversations. The framing evolved through disagreement more than consensus, which is how mental models usually get better.

  • The Notion Operating Company: How to Actually Run a Business on a Workspace in 2026

    The Notion Operating Company: How to Actually Run a Business on a Workspace in 2026

    There is a version of Notion most people use, and there is the version a small number of operators have quietly built — and in April 2026 those two versions are now so far apart that they’re barely the same product.

    The version most people use is a wiki. It is a place you put information you intend to come back to, and most of the time you don’t. Pages go stale. Databases grow faster than they get organized. The search gets worse as the content gets larger. You know this because you have seen your own Notion and felt the tug of guilt when you open it, the small calculation of whether it is worth the effort to fix any of this versus just writing the thing you need to write in a fresh page and adding it to the pile.

    The version a smaller number of people have built is an operating company. It runs on Notion. The human in the chair reads briefs written by AI, approves work, watches reports come back, adjusts priorities, and hands the next job out — and the human never leaves Notion. Everything that is expensive to move between tools does not move. The work comes to them.

    Those aren’t the same product anymore. They used to be. Notion was, for years, fundamentally a block editor with databases bolted on. What changed — what actually changed, not what the vendor said changed — is that over the last six months Notion stopped being a place you put things and started being a place you run things. Custom Agents shipped in late February. The Workers framework followed. MCP support matured. The Skills layer made repeatable workflows into commandable capabilities. What used to be a workspace is now closer to an operating system for a small business.

    Most coverage of this shift is either vendor-positive cheerleading or a product tour disguised as a guide. This is neither. This is how an actual operator runs a real, unglamorous business — dozens of properties, content production cycles, client work, all of it — out of Notion in 2026. The shape, the databases, the ritual, what goes inside the workspace and what stays outside, and where it still breaks.

    If you want a product tour you can find one on Notion’s own blog. If you want the honest operator version, keep reading.


    What “operating company” actually means

    The frame matters, so let’s be concrete about what it is.

    An operating company, in the sense I mean it, is the set of decisions, assets, people, and ongoing commitments that make a business actually go. Not the legal entity. The operating layer. In a traditional small business, that operating company lives in someone’s head, a few spreadsheets, a calendar, a CRM, an email inbox, a project tool, a file drive, a slack, a billing system, and the recurring pain of trying to hold all of it in mind at once.

    Running a business on Notion in 2026 means collapsing as much of that operating layer as possible into a single workspace that knows what it is. Not a place where you write things down. A place where the work is actually happening, where the state of the business is legible at a glance, where a decision made on Monday shows up in Thursday’s automatically-generated brief without anyone having to remember to copy it forward.

    The term I have started using is the Notion Operating Company. It captures the thing correctly: Notion is not the tool you use to run the company, it is the operating layer of the company. The humans make the calls, set the priorities, and absorb the parts that cannot be delegated. Everything else lives in the workspace and operates against the workspace.

    If that sounds like a personal productivity system scaled up, it is not. Personal productivity systems are closed loops. The Notion Operating Company is an open system that other humans, AI teammates, and external services read from and write to. The difference is legibility and composability, and in 2026 those are the qualities that separate a workspace that earns its place from a workspace that is a second pile.


    Why this suddenly works in 2026 (and didn’t in 2024)

    A few things had to be true at the same time for this pattern to become reliably available to small teams and solo operators. None of them were true two years ago.

    Custom Agents shipped. On February 24, 2026, Notion released Custom Agents as part of Notion 3.3. These are autonomous AI teammates that live inside your Notion workspace and handle recurring workflows on your behalf, 24 hours a day, 7 days a week. They do not wait for you to prompt them. You give them a job description, a trigger or schedule, and the data they need, and they run. That one change is the hinge the whole operating-company pattern swings on. Before Custom Agents, automation inside Notion was cosmetic — property updates, templated pages, simple reminders. After Custom Agents, a workspace can actually operate itself between human check-ins.

    The pricing makes it viable. Custom Agents are free to try through May 3, 2026, so teams have time to explore and see what works. Starting May 4, 2026, they use Notion Credits, available as an add-on for Business and Enterprise plans. The pricing matters because it turns out many workflows are cheap enough to run continuously, and the ones that aren’t are easy to audit once the dashboards shipped. Custom Agents are now 35–50% cheaper to run across the board, especially ones with repetitive tasks like email triage. They’re even more cost efficient when you pick new models like GPT-5.4 Mini & Nano, Haiku 4.5, and MiniMax M2.5 that use up to 10× fewer credits. The 10× model-routing move means a well-designed agent for an operator’s workspace costs real-world pennies to run daily.

    MCP connects the workspace to everything else. The Model Context Protocol, opened by Anthropic, gives the workspace a standardized way to reach external tools and services. Notion ships MCP support; most serious AI tools do. The practical consequence: a Custom Agent inside Notion can reach into a source-control system, post to a messaging tool, query a database, or trigger an external worker, without anyone writing glue code. Not every integration is seamless, but the floor has lifted.

    Skills turned workflows into commandable capabilities. Skills turn “that thing you always ask Notion Agent to do” into something it can do on command. Save your best workflows as skills like drafting weekly updates, reshaping a doc in your team’s format, or prepping briefs before a meeting. That matters because the skills layer is where institutional pattern-capture lives. The first time you solve a problem in your workspace, you solve it. The second time, you turn it into a skill. The third time, you invoke it by name. A workspace that accumulates skills gets faster over time instead of slower.

    Autofill became real. Use Autofill to keep your data fresh and up to date, now with all the power and intelligence of Custom Agents. Continuously enrich, extract, and categorize information across every row, so your database stays trustworthy without manual review. That changes what a Notion database is. Databases used to rot without manual maintenance. A self-maintaining database is a different kind of object.

    None of these individually would have tipped Notion from workspace to operating system. All of them together, shipped inside a twelve-month window, did.


    The shape of an operating company in Notion

    Let me describe the actual shape. This is not theoretical. This is the operational pattern that works, stripped of the specifics that would identify any one business.

    The Control Center

    At the root of the workspace is a single page called the Control Center. It is the first page you see when you open Notion. It is the page an AI teammate is told to read first when it is helping you with anything. It is the page a new human teammate reads on day one before they read anything else.

    The Control Center does not contain content. It contains pointers. Specifically:

    • Today — a surfaced view of whatever is actively happening today, pulled from the Tasks database, filtered to today or overdue
    • The live business state — three to five sentences updated continuously (by a Custom Agent, actually) describing where the business is, what is being worked on, what is on fire
    • The database index — a linked block for each operational database, in order of how often you touch them
    • The active projects list — rolled up from the Projects database, filtered to in-flight
    • The week — the current week’s focus, the working theme, what “winning the week” looks like
    • Open loops — the short list of unresolved decisions currently parked waiting for input

    The Control Center is roughly two screens long. It tells you what is happening and gives you the jumping-off points to go deeper. Anything that belongs on the Control Center is either updated automatically or so critical that manual maintenance is worth it.

    The database spine

    Under the Control Center live the operational databases. In a functioning operating company, these map directly to the actual entities the business deals with, not to organizational categories.

    For a service business, the spine typically includes: Clients, Projects, Tasks, Leads, Decisions, People (the humans you interact with externally), Assets, and a catch-all Inbox.

    For a content business, the spine typically includes: Properties (the things you publish on), Briefs, Drafts, Published, Distribution, Ideas, and Performance.

    For a product business, the spine looks different again: Features, Customers, Feedback, Roadmap, Releases, Incidents.

    The exact databases depend on the business. The pattern does not. Each database represents a real operational object. Each relation represents a real dependency. Each view answers a question someone actually asks regularly.

    The test for whether a database belongs on the spine is simple: can you describe, in one sentence, what decision this database helps someone make? If the answer is yes, it belongs. If the answer is “it’s where I put stuff about X,” it doesn’t.

    The agents layer

    Running on top of the database spine is the agents layer. This is the part that would not have existed in 2024.

    The operational pattern, in the workspace I actually run, has a handful of agents that each do one job and do it well.

    • The Triage Agent watches the Inbox database. Anything that lands there gets a priority, a category, and a pointer to the database it actually belongs in. It does not make big decisions. It takes the pile and turns it into a sorted pile.
    • The Morning Brief Agent runs once a day. It reads the Control Center state, the active projects, the top of the Tasks database, the calendar, and the unresolved Decisions, and writes a three-paragraph brief at the top of today’s Daily page. You wake up and the state of the business is already synthesized.
    • The Review Agent runs weekly on Fridays. It pulls what was completed, what stalled, and what slipped, and writes the weekly retro. It is not asking you to fill in a form. It is writing the retro and handing it to you to review.
    • The Enrichment Agent runs on database writes. When something new lands in a key database — a lead, a project, a decision — the agent fills in the fields that would otherwise require manual data entry. Research, links, categorization.
    • The Escalation Agent watches for states that require human attention. A project stalled for too long, a task with no owner, a decision parked past its decide-by date. It surfaces them on the Control Center.

    That’s five agents. Some workspaces I’ve seen run more. Most run fewer. The number is not the point; the pattern is: each agent has one job, one data source, one output surface, and a clear signal for when it should run.

    The constraint that keeps this from sprawling into chaos is a rule I’ve internalized: one agent, one job. The moment an agent tries to do three things, it does none of them well.

    The skills layer

    Beneath the agents, you accumulate skills over time. These are not agents; they’re invoked capabilities. “Generate a weekly client report in this format.” “Convert this meeting transcript into tasks.” “Draft a response to this inbound email in my voice.” Skills are the pattern-capture layer — the place where solved-problems become invocable capabilities.

    The skills layer grows by a specific rule: the third time you notice yourself doing the same thing manually, you turn it into a skill. Not the first time, not the second. The third time is the signal that it’s going to happen again, and the cost of capturing it is less than the cost of doing it manually from here forward.

    The source-of-truth boundary

    Here is where most Notion-as-OS writeups go silent, and it’s actually the most important thing in the whole pattern.

    Notion is not the source of truth for everything. It is the source of truth for the operational state of the business — what’s happening, what’s decided, what’s being worked on, what’s next. It is not the source of truth for code, for financial transactions, for legal documents, for anything that needs to survive an outage of Notion itself.

    Code lives in a source-control system. Money data lives in whatever financial system the business uses. Legal artifacts live in signed-document storage. Heavy compute runs outside Notion and reports back. The operating company is inside Notion; the substrate is not.

    The mental model I use: Notion is the bridge of the ship. The bridge runs the ship. The ship is not inside the bridge.

    This distinction is what prevents the whole pattern from collapsing. A workspace that tries to be the whole business eventually becomes unusable because it is bloated with content that doesn’t belong in a control plane. A workspace that is a control plane stays light, stays fast, and stays legible.


    The daily ritual (what it actually looks like)

    The pattern lives or dies in daily use. Let me describe what a normal working day looks like for an operator running on this pattern — the actual sequence, not the aspirational version.

    Open Notion. The Control Center loads. The Morning Brief Agent has already run; the top of today’s Daily page has a three-paragraph synthesis of the state of the business: what’s on fire, what’s progressing, what requires a decision today. Reading that takes ninety seconds.

    Scan the Inbox. The Triage Agent has already sorted whatever landed overnight. Each item has a category, a priority, and a pointer. You’re not doing the sort. You’re spot-checking the sort — agreeing, disagreeing, occasionally fixing, and dispatching the important items into their real databases.

    Check Escalations. The Escalation Agent has flagged the three things that need attention. You make the decisions. This is the part where being a human matters.

    Open today’s active project. Whatever you are actually working on is linked from the Control Center. You go there and do the work. Sometimes the work is writing in Notion. Sometimes the work is in an IDE, a chat window, a document, a call — Notion is where you come back to log what happened and what comes next.

    At a natural stopping point, log. The log is short. Two sentences on what just got done. Notion captures the timestamp. Over time the log becomes the actual record of how the business moves.

    Evening wrap. Five minutes. The day’s work closes out. Anything that didn’t get done gets re-dated. Tomorrow’s active page pre-stages.

    That’s the ritual. It takes under twenty minutes of overhead per day and gives you a fully legible operating record. The agents do the work that would otherwise be overhead. The human does the work that requires a human.

    The difference between an operator running this pattern and an operator running without it is not productivity on any individual task. It is the absence of the context-loss tax — the tax you pay every time you sit down and have to remember where you left off, what’s happening, what’s next. Pay that tax once a day at the beginning of the brief, and the rest of the day runs on continuous context.


    Where it still breaks (the honest part)

    This pattern is not finished. There are specific places where running a real operating company on Notion still hits walls, and pretending otherwise is the kind of dishonesty that catches up to you when the tool fails you at a bad moment.

    Heavy write workloads. Notion is not a database in the performance sense. If you are trying to push hundreds of updates per minute through the API, you are going to hit rate limits and you are going to have a bad time. The operational pattern is aware of this: heavy writes go to a real database first and are reflected into Notion in summary form.

    Reliable external integration. Custom Agents’ ability to reach external systems via MCP has improved a lot in 2026, but it is not ironclad. Agents that must succeed — send this email, charge this card, update this record — still belong in a purpose-built service, not in a Custom Agent. The rule I use: if the cost of the agent silently failing is real money or real trust, it doesn’t belong in Notion.

    Mobile agent management. Building, editing, and configuring Custom Agents requires the Notion desktop or web app. Mobile access for viewing and interacting with existing agents is supported, but agent creation and configuration is desktop/web only. This is fine but worth knowing. Operators who work primarily from phone can interact with agents but cannot build them on the go.

    Prompt injection. Custom Agents can encounter “prompt injection” attempts — when someone tries to manipulate an agent through hidden instructions in content it reads. This risk exists across connected tools, uploaded documents, and even internal communications. Notion has shipped detection, but the attack surface is real and growing. The practical operator response: don’t give agents access to anything they don’t strictly need, and review any external content an agent will read before granting access.

    The shape of the workspace matters more than it used to. A messy Notion workspace was merely annoying in 2024. A messy Notion workspace in 2026 makes your agents worse, because the agents are navigating the same structure you are. Disorganized databases produce disorganized agent outputs. The cost of workspace hygiene used to be cosmetic. It’s now functional.

    Credit economics at scale. Starting May 4, 2026, Custom Agents run on Notion Credits, a usage-based add-on available for Business and Enterprise plans. The pricing is $10 per 1,000 credits. Credits are shared across the workspace and reset monthly. Unused credits do not roll over to the following month. For a small operator, this is fine. Most workflows are cheap. For larger teams running many agents, credit consumption becomes a line item worth watching. Notion has shipped a credits dashboard to help, but budget discipline is a new muscle for Notion-native teams.

    None of these are dealbreakers. All of them are things the pattern has to work around. The honest version of this article tells you that up front.


    Notion Agent vs Custom Agents (the distinction that matters)

    One clarification because the terminology can confuse newcomers to the pattern.

    Custom Agents are team-wide AI teammates that run automatically on schedules or triggers. Notion Agent is a personal AI assistant that works on-demand when you ask. All Notion users get Notion Agent. Business and Enterprise customers get Custom Agents, priced under the Notion credit system.

    The operating-company pattern uses both. Notion Agent is the on-demand assistant — the one you invoke for “rewrite this paragraph” or “summarize this doc” or “find me every page that mentions X.” Custom Agents are the autonomous teammates that run the background rhythms.

    The mistake to avoid: trying to use Notion Agent for the background rhythms. It is not built for that. It runs when you ask. Custom Agents run when the world changes or when a schedule says so. Those are different tools for different jobs.


    Who this pattern is for

    To be clear about who gets the most out of the Notion Operating Company pattern:

    • Solo operators running real businesses. The leverage is highest here because there is no team to argue with about conventions. You decide the shape, you live in it.
    • Small teams (3–15 people) with a strong operational function. The pattern works if one person owns workspace architecture. It breaks if everyone is allowed to add databases and pages ad-hoc without a maintaining hand.
    • Agencies and consultancies running multi-property operations. Anywhere you need to coordinate lots of parallel work and keep the whole portfolio legible to one or two humans.
    • Knowledge-heavy businesses. Law firms, research shops, content operations, advisory services. The operating company pattern rewards businesses where the value is produced by synthesis across prior work.

    Where the pattern fits less well: businesses where most of the work happens outside any tool (field services, physical retail, manufacturing floors). Notion can still run the management layer, but most of the actual operational data lives elsewhere.


    How to start without building a cathedral

    The pattern I’ve described can sound like a project. It isn’t. Or rather, it can be — people build beautiful elaborate versions for a year and never actually use them. The better path is embarrassingly small steps.

    Week one: build the Control Center. Just that page. Two screens long. Link to the databases you already have, even if they’re messy. The Control Center is the anchor; everything else will build against it.

    Week two: add one Custom Agent. Pick the simplest high-frequency job you do manually. The Triage Agent is a good first choice. Let it run for a week. Watch what it gets right. Adjust.

    Week three: add the Morning Brief Agent. This is the one that changes how your days open. If it works, you will know because opening Notion will stop feeling like work and start feeling like a starting line.

    Week four: look at your databases. The ones that matter will be obvious because the agents will be using them. The ones that don’t matter will be collecting dust. Delete or archive the dead ones. Formalize the live ones.

    After that, the pattern compounds. Each thing you do manually three times becomes a skill. Each repeated workflow becomes an agent. Each messy database gets cleaned when an agent trips on it. The workspace gets smarter as a function of use, not as a function of a weekend rebuild project.

    The operators I’ve seen succeed with this pattern have a specific characteristic in common: they started small and kept going. The operators I’ve seen fail had grand plans and never got to week four.


    What “AI-native business” actually means (if we have to use the phrase)

    The term “AI-native” gets thrown around enough to lose meaning. Inside this pattern, it means something specific.

    An AI-native business is one where AI is not a tool you pick up to accomplish a task. It is a teammate that is already in the workspace, already reading the state, already surfacing what matters, already handling the rhythms. The human is not using AI. The human is working with an operating company that has AI embedded into its substrate.

    That is what the Notion Operating Company pattern produces. Not a workspace that is faster because AI is speeding things up. A workspace that operates continuously because the AI is running inside it, and the human shows up to make the calls that only a human can make.

    This is why I wrote at the beginning that the version of Notion most people use and the version a smaller number have built are barely the same product anymore. They are not. They are two different conceptions of what a workspace is for, and in April 2026, one of them is still a place you put things, and the other is a place you run things.

    The whole game is picking the second one on purpose.


    FAQ

    What’s the difference between using Notion as a wiki and running an operating company on Notion? A wiki is where information lives after you’re done with it. An operating company is where the work actually happens — briefs, decisions, run reports, active projects, agents handling recurring rhythms. The operating company pattern treats Notion as a control plane, not an archive.

    Do I need Business or Enterprise plan? For Custom Agents, yes. Custom Agents require Notion’s Business or Enterprise Plan. Notion Agent (the on-demand personal AI) is available to all Notion users. The operating-company pattern benefits substantially from Custom Agents, so most serious implementations are on Business or higher.

    How much does this cost to run? Custom Agents are free to try through May 3, 2026. Starting May 4, 2026, they use Notion Credits, available as an add-on for Business and Enterprise plans — $10 per 1,000 credits, shared across the workspace, reset monthly, no rollover. In practice, for a solo operator or small team running five or so agents, credit costs are modest. Budget discipline becomes relevant at larger scale.

    What AI models can the agents use? Currently available: Auto (Notion selects), Claude Sonnet 4.6, Claude Opus 4.7, and GPT-5. Notion regularly adds new models, so expect this list to evolve. Recent additions include cost-efficient models like Haiku 4.5 and GPT-5.4 Mini/Nano that can cut credit usage significantly.

    How secure is it? Custom Agents inherit your permissions, so they can see what you see. They offer page-level access control. Every agent run is logged with full audit trails. Notion has implemented guardrails to automatically detect potential prompt injection, and has built controls for admins and workspace owners to monitor connections and restrict what agents can access. The honest answer: reasonable security defaults, real attack surface, practical precautions apply (scope agents narrowly, audit connected sources).

    Can I run this pattern solo? Yes. Solo operators get the highest leverage from the operating-company pattern because there’s no team coordination overhead. The pattern scales down cleanly.

    What if I don’t want to use Custom Agents? Does the pattern still work? The database spine and Control Center work without agents. You’ll be doing manually what the agents would be doing — daily briefs, triage, weekly reviews. The pattern is still more legible than a traditional Notion setup; you just don’t get the “workspace operates itself between check-ins” effect.

    How long does it take to build? The honest answer is you never stop building. You never should. A workspace that stops evolving is a workspace that is about to stop working. But the minimum viable version — Control Center, one agent, a handful of databases — is a week of part-time work, not a project.


    A closing observation

    The reason this pattern is worth writing about now, in April 2026, is that the window where it is a genuine edge is probably short. Two years from now, some version of this will be the default way Notion is used, and the advantage will compress. Today, most workspaces are still wikis. The operators who make the switch to operating-company now are buying a year or two of operational leverage that becomes the baseline eventually.

    But for right now, this works, it is real, and almost nobody is doing it. That gap is the thing.

    If you are already running something like this, you know. If you are reading about it for the first time, the starting point is the Control Center and one agent. Build the Control Center this week. Add the agent next week. In a month, you’ll have a workspace that is a different kind of object than the one you started with.

    That’s what we mean by an operating company.


    Sources and further reading

  • Everett Housing Market Mid-April 2026: One City, Three Very Different Markets

    Everett Housing Market Mid-April 2026: One City, Three Very Different Markets

    Q: What’s happening in Everett’s housing market right now?

    A: Citywide, the median Everett home is selling for around $547,000 — down roughly 11.6% from a year ago, with homes going pending in about 8 days and selling within 1% of list price. But the neighborhood-level numbers tell a very different story. Downtown Everett is *up* 11.4% year-over-year. Northwest Everett — the stately old-money neighborhood above the waterfront — is up 22.1%. And the 98208 zip code on the south end is down 7.5%. One Everett, three very different markets.

    The headline number for Everett housing in early 2026 is grim if you’re a seller and encouraging if you’re a buyer: citywide, the median home is selling for $547,000, which is 11.6% below where it sat a year ago. The market is still moving fast — 8 days to pending, roughly 1% under list — but the price trajectory has turned.

    Pull one layer back from that headline, though, and the picture fractures. Different corners of Everett are in genuinely different markets right now. If you’re pricing a sale, underwriting a purchase, or watching your own home value, the number that matters isn’t the citywide median. It’s the number for your block.

    Here’s what we’re tracking neighborhood-by-neighborhood, based on the most recent Redfin data available as of mid-April 2026.

    The Citywide Snapshot

    Median sale price: ~$547,000 Year-over-year change: Down 11.6% Median price per square foot: $394 (up 0.9% YoY) Days on market to pending: ~8 Sale-to-list ratio: ~99% (homes selling about 1% under asking)

    A 11.6% year-over-year decline is, by any historical measure, a significant correction. It is not, however, a 2008-style correction. The speed of sale is still fast. Price-per-square-foot is holding steady. The market is still functional. What’s happening is that the feverish appreciation of 2021–2023 has normalized out, and Everett is settling into a version of its market that looks more like 2019 than like 2022.

    That settling is happening unevenly.

    Downtown Everett — Up 11.4% YoY

    The surprise of this cycle is downtown.

    Median sale price: ~$384,000 Year-over-year change: Up 11.4%

    Downtown Everett has historically been the most affordable submarket in the city — lots of older condos, aging multi-family stock, a mix of rental and owner-occupied product that rarely commands premium pricing. That is all still true. What’s changed is the direction of the trend.

    The obvious catalyst is everything that’s been happening physically downtown over the last 24 months. Tapped Public House and Restaurant Row. The Schack Art Center’s spring programming. The Historic Everett Theatre. Funko HQ’s continued pull. The AquaSox stadium site plan, even without shovels in the ground, is visibly changing what a ground-floor unit on Hewitt or Wetmore is worth. And the Edgewater Bridge is about to open on April 28, which cuts what was a gnarly detour for a lot of downtown-proximate commutes.

    If you bought a downtown condo in 2023 or 2024 when the citywide market was peaking and you watched your paper value slide, your value has probably recovered and then some, even as the citywide average has fallen.

    A rising downtown is a real shift in how the rest of the city’s housing market is going to work. Demand for walkable, amenity-dense urban product has been building for a decade in Seattle and finally has a credible competitor on the north end.

    Northwest Everett — Up 22.1% YoY (As of October 2025)

    Median sale price: ~$705,000 Year-over-year change: Up 22.1% (data from October 2025)

    Northwest Everett is the historic mansion district — the bluff above the waterfront, the big old homes on Rucker and Grand and Hoyt, the streets that were Everett’s money before the mills came in. It has always traded at a premium to the citywide average, and in the most recent data available it has appreciated at the fastest clip of any Everett neighborhood.

    A $705,000 median in NW Everett at a +22.1% YoY pace is a market that’s being pulled by two things. One is the same thing pulling downtown — everything happening on the waterfront is making the bluff above the waterfront more valuable. The other is housing stock scarcity. NW Everett doesn’t have teardown-and-build-a-fourplex density potential the way some newer parts of Everett do. What’s there is largely what’s there. When demand for character-rich historic homes in Puget Sound spikes, NW Everett is one of the first submarkets to reprice.

    The October 2025 reading is the most recent neighborhood-level number available on Redfin as of this writing. The direction of the citywide trend since then suggests the appreciation pace has probably moderated in 2026, but the relative premium is not going anywhere.

    98208 — Down 7.5% YoY

    Median sale price: ~$740,000 Year-over-year change: Down 7.5% (as of January 2026)

    Zipcode 98208 is the south-and-east chunk of Everett — Silver Lake, a good portion of the Cascade High School attendance boundary, the areas that functionally blend into unincorporated Snohomish County. It’s where a lot of Everett’s 1990s and 2000s single-family stock sits. It’s also where a lot of the most recent in-migration from Seattle has landed since 2020.

    That in-migration is what’s unwinding. 98208 saw some of the strongest appreciation during the 2021–2023 boom, and it’s now seeing some of the sharpest year-over-year declines. A $740,000 median is still substantial — higher than the citywide number — but it’s down from a peak around $800,000.

    If you’re buying in 98208 right now, the deals are better than they’ve been in three years. If you’re selling, you’re competing against more inventory than NW Everett or Downtown sellers are, and the negotiation leverage is on the other side of the table.

    What It Means for Different Everett Buyers

    First-time buyer

    Downtown is actually your best entry point right now. $384,000 median for a downtown condo is a number that, with a VA or FHA loan, is within reach for a dual-earner household at Everett’s median household income. You’re buying a smaller unit, but you’re buying into a trajectory. The +11.4% YoY in downtown is what appreciation looks like when the fundamentals around a neighborhood genuinely improve.

    Move-up buyer

    98208 is your buy. If you already own a smaller unit and you’re looking to trade up into a 3-4 bedroom single-family home, the citywide market is softer than it’s been since 2019, and the 98208 submarket specifically is down more than the citywide average. Your existing property’s paper value may be softer than you’d like, but you’re buying into a deeper discount than you’re selling out of.

    Investor / developer

    Watch Millwright District pre-leasing and Waterfront Place Restaurant Row lease-up as leading indicators for downtown. If the foot traffic and tenant demand at Waterfront Place keeps trending the way it has, downtown appreciation is going to keep outrunning the citywide average for at least another cycle. The investment thesis for small downtown multi-family right now is specifically the Waterfront Place thesis.

    Seller

    Price it sharp. Eight days to pending doesn’t mean every home is getting multiple offers. It means well-priced homes move fast and overpriced homes get stale fast. The citywide market is down 11.6%; don’t anchor to what your neighbor got in 2022. Talk to an agent who’s closed deals in the last 90 days in your specific zip code.

    What to Watch Next

    Three things that could move the neighborhood numbers between now and the end of summer 2026:

    • The downtown stadium vote on April 29. The City Council is being asked for $10.6 million in design funding. If the vote passes and the stadium project stays on track, downtown appreciation gets a structural tailwind. If it doesn’t, the most bullish part of the downtown thesis cools off.
    • Sound Transit Everett Link decisions. The Draft EIS is expected this year. Any final decision — in either direction — on the Everett Link extension will move downtown and waterfront-adjacent pricing materially.
    • Millwright District Phase 2 leasing traction. 120,000 square feet of waterfront office space is being pre-leased right now. Which tenants sign determines what downtown’s weekday population looks like in 2027–2028, which determines what downtown condo rents do next.

    The Everett housing market of 2026 is a market in transition. The story is not “Everett is up” or “Everett is down” anymore. It’s “which Everett.”

    Frequently Asked Questions

    What is the median home price in Everett right now? Approximately $547,000 citywide, down 11.6% year-over-year as of early 2026.

    Which Everett neighborhood is appreciating fastest? Northwest Everett posted the strongest recent year-over-year gain at approximately +22.1% as of October 2025 data, with a median sale price around $705,000.

    Which Everett neighborhood is the most affordable? Downtown Everett is the most affordable submarket, with a median around $384,000 — though it’s now appreciating at +11.4% YoY as the Waterfront Place and downtown revitalization story accelerates.

    How quickly are Everett homes selling? Homes in Everett are going pending in approximately 8 days on average, selling at roughly 1% below list price.

    Is it a buyer’s market or a seller’s market in Everett? It’s a mixed market. Citywide prices are down meaningfully year-over-year, which gives buyers leverage, but sale speed (8 days to pending) remains fast, which works in sellers’ favor if pricing is sharp. By neighborhood, Downtown and Northwest Everett lean seller, 98208 leans buyer.

    Where is Everett housing most softening? The 98208 zip code on Everett’s south side was down 7.5% year-over-year as of January 2026, with a median around $740,000. This is the submarket that appreciated most aggressively during 2021–2023.

    How should I think about Everett housing in 2026 overall? Don’t use the citywide number to value your specific home. Neighborhood-level variance in Everett right now is wider than citywide averages would suggest. A real estate agent who has closed recent deals in your specific zip code will give you a much more accurate number than a citywide aggregate.

  • Waterfront Place’s Next Wave: Menchie’s and Marina Azul Are Almost Open — And Alexa’s Cafe Is Out

    Waterfront Place’s Next Wave: Menchie’s and Marina Azul Are Almost Open — And Alexa’s Cafe Is Out

    Q: Who’s opening next at the Port of Everett’s Restaurant Row?

    A: Two new tenants are days to weeks away from opening at Waterfront Place: Menchie’s at the Marina (frozen yogurt, second floor of the new Restaurant Row building) and Marina Azul Cocina & Cantina (from the team behind Casa Azul in Woodinville and Agave Cocina in Issaquah). Both are expected in early spring 2026. Alexa’s Cafe — originally slated to be the breakfast-and-brunch tenant — has pulled out, and the Port is now actively searching for a new café operator to fill the last remaining spot in the building.

    Walking Waterfront Place in mid-April, you can feel that the second wave has landed. Tapped Public House’s rooftop is already pulling weekend crowds. Rustic Cork and The Net Shed Fresh Fish Market & Kitchen, both of which opened quietly in December 2025, are no longer “new” — they’re already part of the weekday regular rotation for a lot of downtown workers.

    But the building still has two tenants wrapping up construction, one that’s quietly vanished from the tenant list, and one visible empty storefront waiting for its operator.

    Here’s what we’re tracking in the final phase of the Restaurant Row lease-up at the Port of Everett.

    Menchie’s at the Marina — Opening Early Spring 2026

    The waterfront’s first national-brand dessert concept is going in on the second floor of the Restaurant Row building, a level up from where Tapped has its giant rooftop deck. If you’ve been to a Menchie’s anywhere else, you already know the deal — self-serve frozen yogurt, a wall of rotating flavors, a toppings bar, pay by weight.

    What makes this location different is the setting. Menchie’s hasn’t had a waterfront storefront anywhere in the Puget Sound region before, and putting one on the upper deck at Waterfront Place — with views out across the North Marina — turns what’s otherwise a suburban mall concept into something that reads a lot more like vacation-mode soft-serve. The Port has been positioning the full Restaurant Row building as a destination for families as much as for weekend drinkers, and Menchie’s is part of that case.

    The Port’s public communication says “early spring 2026,” which at this point in April is a window measured in weeks, not months. Watch for the signage to go up on the second-floor exterior first, then the lighting and cabinet fit-out in the back-of-house windows, then the soft open.

    Marina Azul Cocina & Cantina — From a Team You Probably Already Know

    The bigger food story, honestly, is Marina Azul.

    Marina Azul Cocina & Cantina is the third concept from the team behind Casa Azul Cocina and Cantina in Woodinville and Agave Cocina and Cantina in Issaquah. Both are well-regarded regional Mexican restaurants with strong happy hour programs and a family-owned operational style that Eastside diners have been sending Yelp reviews about for years.

    Putting their first waterfront location at the Port of Everett is a decision that says something about where they think the Eastside customer and the North Sound customer are going to overlap next. Woodinville and Issaquah are both destination-dining towns. Everett, with 110,000 residents and a brand-new waterfront, is on the verge of being one. A Friday evening in April at Fisherman’s Harbor already feels a lot more like a weekend in Leavenworth or Bellevue Collection than it used to.

    Marina Azul is taking ground-floor space directly on the water — the kind of setup where you can dock a boat, walk up to the deck, and be eating tacos and drinking a paloma within 10 minutes. That’s a very specific restaurant experience Everett just hasn’t had before, and it’s the kind of thing that starts pulling regional weekend traffic in a way Hewitt Avenue alone doesn’t.

    Expected opening: early spring 2026. Which again means weeks, not months.

    The Alexa’s Cafe Situation

    Here’s the interesting wrinkle we should flag honestly.

    Alexa’s Cafe was the originally announced breakfast-and-brunch tenant for the Restaurant Row building, going back to a Port press release in April 2024. That lease did not end up closing. Alexa’s is no longer a Waterfront Place tenant, and the Port is now actively searching for a new breakfast-and-brunch operator to take the last remaining space in the building.

    This isn’t a scandal — lease deals collapse in commercial real estate all the time, and a year-and-a-half gap between a press announcement and a signed lease is well within the normal range for a waterfront concept needing custom buildout. But it does mean the final tenant in the Restaurant Row building is currently a gap on the tenant list, not a named business.

    The Port has publicly said it wants a “breakfast and brunch café” concept specifically. If you’re a café operator in the North Sound market or you know one who’s been quietly looking at expansion, the Port’s real estate team is the place to send the inquiry.

    What’s Actually Open at Waterfront Place Right Now

    For the current scorecard, here’s what you can actually walk into at Waterfront Place as of mid-April 2026:

    • Tapped Public House — gastropub, largest open-air waterfront rooftop deck in Snohomish County. Opened March 2, 2026.
    • Rustic Cork Wine Bar — second floor of Restaurant Row building. Opened December 2025.
    • The Net Shed Fresh Fish Market & Kitchen — ground-floor fresh fish market and quick-service seafood. Opened December 2025.
    • S3 Maritime — marine maintenance and repair services, now open at the marina. (Not a restaurant, but it’s new and worth knowing about.)
    • Pacific Coast Salmon Coalition gift shop — the Port’s retail anchor from the first phase.
    • Hotel Indigo Everett Waterfront — still the only hotel at Waterfront Place, with the Bluewater Distilling restaurant on the ground floor.

    What’s Coming Next

    And here’s what’s still on deck between now and summer:

    • Menchie’s at the Marina — early spring 2026 (weeks out)
    • Marina Azul Cocina & Cantina — early spring 2026 (weeks out)
    • Unnamed breakfast-and-brunch café — Port actively recruiting, no signed tenant yet
    • Flagship restaurant at the last undeveloped parcel — Port opened an official search in early 2026; we covered that story separately

    That’s three tenants still to sign or open in a footprint that, 18 months ago, didn’t have a single operating restaurant. The pace of lease-up at Waterfront Place has been honestly faster than most commercial retail deliveries of comparable scale in the Puget Sound market over the last five years.

    Why This Matters for Everett

    It’s easy to look at restaurant openings as a soft story — lifestyle news, not real economic development. But the Restaurant Row lease-up is doing three specific things for Everett right now:

    First, it’s generating foot traffic that didn’t exist in this part of town 24 months ago. The Port has reported significant year-over-year increases in marina visitation since the first Restaurant Row tenants opened, and that foot traffic is spilling into the Hotel Indigo, into Jetty Island day-use traffic, and into the Mukilteo–Everett water taxi seasonal ridership.

    Second, it’s proving the commercial real estate thesis for Millwright District next door. Millwright Phase 2 — housing plus 120,000 square feet of office space — is being pre-leased right now. Every tenant that signs in Millwright is underwriting that decision against the foot traffic and the destination-draw of Waterfront Place. Restaurant Row is, in a direct way, making the Millwright deals close.

    Third, it’s generating the sales tax and lodging tax that funds basically everything else the Port and the City can pay for downtown. Hewitt Avenue’s slow rebuild into a restaurant district, the Edgewater Bridge opening April 28, the ongoing conversation about the Sound Transit Everett Link extension — all of those projects have better financing math when downtown and the waterfront are generating more taxable activity.

    Menchie’s and Marina Azul are, on one level, a frozen yogurt shop and a Mexican restaurant. On another level, they’re two more data points in the slow-motion argument that downtown Everett is becoming the kind of place where a regional restaurateur wants to sign a 10-year lease.

    Both of those things get to be true.

    Frequently Asked Questions

    When is Menchie’s at the Marina opening at Waterfront Place? Early spring 2026. The Port has not announced a specific date, but the language suggests weeks rather than months from mid-April.

    When is Marina Azul Cocina & Cantina opening? Early spring 2026. The restaurant is from the team behind Casa Azul in Woodinville and Agave Cocina in Issaquah.

    Is Alexa’s Cafe still opening at Waterfront Place? No. Alexa’s is no longer a Waterfront Place tenant. The Port is actively recruiting a new breakfast-and-brunch operator to take that last spot in the Restaurant Row building.

    Which restaurants are already open at Waterfront Place? Tapped Public House, Rustic Cork Wine Bar, and The Net Shed Fresh Fish Market & Kitchen are the three most recent openings. Bluewater Distilling at the Hotel Indigo and the Port’s retail tenants anchor the first phase.

    Where is Marina Azul Cocina & Cantina located? Ground-floor space on the water at Waterfront Place, adjacent to the Restaurant Row building. The restaurant has direct waterfront exposure toward the marina.

    Who operates Menchie’s at the Marina? Menchie’s is a national frozen yogurt franchise. The individual franchise operator for the Waterfront Place location has not been publicly named.

    Is the Port still looking for more Restaurant Row tenants? Yes. The Port is actively searching for a breakfast-and-brunch café operator for the remaining Restaurant Row building slot, and in a separate process is recruiting a flagship restaurant for the last undeveloped waterfront parcel at Waterfront Place.

  • Everett’s Light Rail Showdown: What the April 14 Town Hall and the Somers Plan Mean for Snohomish County

    Everett’s Light Rail Showdown: What the April 14 Town Hall and the Somers Plan Mean for Snohomish County

    Q: Is Everett’s light rail extension still getting built?

    A: It’s still in the plan — but Sound Transit is staring down a $34.5 billion budget shortfall, and three of the agency’s cost-cutting scenarios would either shorten or delay the Everett connection. Snohomish County Executive Dave Somers, who chairs the Sound Transit Board, pledged at the April 14 town hall in Everett that he’ll push a plan prioritizing the north-south spine — including Everett — over Seattle-area extensions. The fight over what actually gets funded happens in the next several months.

    We packed into Everett Station on Tuesday night, April 14, and it felt less like a transit meeting and more like a civic defense. Residents, small-business owners, transit nerds, skeptical commuters, and a row of Snohomish County officials spent the evening doing one thing — reminding Sound Transit that Everett has been paying for light rail for more than a decade, and we intend to get the light rail we’ve been paying for.

    If you’ve been half-following the Everett Link Extension saga, here’s where things stand right now.

    The $34.5 Billion Problem

    Sound Transit is facing a $34.5 billion budget shortfall across its ST3 program. That’s not a typo, and it’s not a projection for the distant future — it’s the gap between what the agency is required to build and what it can currently afford.

    In March, the agency put three illustrative cost-cutting scenarios on the table. All three involve cuts. One of the three scenarios would not complete the connection to Everett at all. The other two would shorten or delay extensions elsewhere — Ballard, West Seattle, Tacoma, Issaquah — but they still put pressure on the northern end of the spine, which is us.

    That’s the context for the April 14 town hall. It wasn’t an informational session. It was Everett saying: don’t you dare.

    What Somers Actually Said

    County Executive Dave Somers, who also chairs the Sound Transit Board, didn’t hedge. He told the room he plans to present a proposal to the full Sound Transit Board that prioritizes completing the north-south corridor — Everett to Tacoma — over extensions into areas that are already served by light rail.

    The quote that traveled was this one: “The citizens of Snohomish County have been paying for a system for a long, long time, and it’s time for them to get a light rail.”

    He was more specific about what that plan looks like in practice. Seattle-area projects — Ballard, West Seattle — would stay alive in planning but would not be authorized to move forward until the agency can actually afford them. “We will keep those projects alive in planning, but they will not be authorized for moving forward, because we can’t afford them right now.”

    Somers also told the room the obvious political truth: his is one voice among 18 on the Sound Transit Board. “That’s eight votes out of 18, so there’s 10 votes that are outside our control.” He’s going to need allies from Pierce County and from King County to get this across the finish line.

    Mayor Franklin’s Frame: “The Spine”

    Everett Mayor Cassie Franklin reinforced Somers with a framing device that matters for anyone trying to understand regional transit politics: the spine.

    “It is the spine from Everett to Tacoma that is actually going to connect this region.”

    The idea is that ST3 was never sold to voters as a series of disconnected spur lines. It was sold as a regional system with a north-south backbone. Cutting Everett off the spine isn’t a line-item reduction — it’s a structural amputation. Franklin’s argument is that if you want to know which projects are most essential to a regional transit system, you start with the backbone and work outward.

    That framing is a strategic move. It reframes the debate from “which extension is most deserving” to “which projects are structural versus which are peripheral.”

    The Timeline We’re Looking At

    The Everett Link Extension is currently not expected to open until sometime between 2037 and 2041. That’s a range we should all sit with for a minute. The original target was 2036. The most optimistic current estimate is one year later than originally promised. The least optimistic is five years later.

    This is before any of the three cost-cutting scenarios get applied.

    The extension would add 16 miles of light rail and six new stations connecting Snohomish County into the broader regional network. The Draft Environmental Impact Statement is expected to be available for public review and formal comment in 2026, which means there is going to be a real window for residents to weigh in on this project in writing.

    What Voters Are Actually Angry About

    Walking out of the town hall, the argument that kept surfacing in conversations in the parking lot was a version of the one Kevin Ballard made in his April 20 letter to the editor in the Herald: we’ve been paying for this for over a decade. If the project gets delayed or scaled back, the money we’ve already paid doesn’t come back to us. It just gets spent somewhere else.

    There’s a version of this argument that’s about fairness — we paid, we deserve delivery. There’s another version that’s about math — Everett’s segment of ST3 is, by most measures, among the most cost-efficient in the entire package, which means cutting it would actually be a bad deal for the agency’s budget. Neither version is a closing argument, but both are going to be heard a lot over the next several months.

    What’s Next

    The Sound Transit Board meets on the fourth Thursday of each month from 1:30 to 4:00 p.m. Public comment is accepted at those meetings. Written comments can also go to meetingcomments@soundtransit.org.

    The Draft Environmental Impact Statement is expected this year. When it lands, there will be a formal public comment period.

    Somers has said he’ll bring his north-south-first proposal to the Board. We don’t know exactly when, but the implication from the town hall is that this is not a fall 2026 conversation — it’s a next-few-months conversation.

    And locally, Everett City Council and the Snohomish County Council have both started putting resolutions and letters of support behind the completion of the spine. That drumbeat is going to get louder before it gets quieter.

    What This Means for the Waterfront

    Everett’s waterfront transformation — Waterfront Place, Millwright District, the downtown stadium, Restaurant Row — is happening on the assumption that light rail is coming. The Everett Station location anchors the southern edge of downtown, and a future Everett Station-to-Waterfront connection is part of how downtown’s long-term density math actually works.

    If the Link extension gets shortened or delayed further, the case for downtown office, retail, and residential investment doesn’t collapse — but it does get harder. Developers project rent rolls on 30-year time horizons. A 2041 light rail opening versus a 2036 opening is the kind of thing that shows up in a capital stack.

    It’s also the reason why this is a waterfront story, not just a transit story. Everything Everett is building downtown right now — the stadium, the Millwright office space, the housing being pre-leased at Waterfront Place — is happening in front of a fundamental question about whether the city will be a light rail terminus or a light rail afterthought.

    Frequently Asked Questions

    When was the Sound Transit town hall in Everett? Tuesday, April 14, 2026, at Everett Station. Local officials and Sound Transit staff presented the agency’s budget situation and took public comment.

    Who chairs the Sound Transit Board? Snohomish County Executive Dave Somers. He has publicly committed to advocating for completion of the Everett Link Extension as part of the north-south spine.

    How big is Sound Transit’s budget shortfall? $34.5 billion across the ST3 program. Three cost-cutting scenarios are being considered; one would not complete the Everett extension.

    When is the Everett Link Extension expected to open? Currently projected between 2037 and 2041. The original target was 2036.

    How many new stations would the Everett extension add? Six new stations across 16 miles of new light rail.

    How can Everett residents weigh in on this decision? Attend Sound Transit Board meetings (fourth Thursday of each month, 1:30–4:00 p.m.), submit written comments to meetingcomments@soundtransit.org, and watch for the Draft Environmental Impact Statement comment period later in 2026.

    What is “the spine” Mayor Franklin refers to? The north-south light rail corridor from Everett to Tacoma — the backbone of the ST3 system, distinct from the east-west extensions to Ballard, West Seattle, and Issaquah.

  • The CLAUDE.md Playbook: How to Actually Guide Claude Code Across a Real Project (2026)

    The CLAUDE.md Playbook: How to Actually Guide Claude Code Across a Real Project (2026)

    Last refreshed: May 15, 2026

    Most writing about CLAUDE.md gets one thing wrong in the first paragraph, and once you notice it, you can’t unsee it. People describe it as configuration. A “project constitution.” Rules Claude has to follow.

    It isn’t any of those things, and Anthropic is explicit about it.

    CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there’s no guarantee of strict compliance, especially for vague or conflicting instructions. — Anthropic, Claude Code memory docs

    That one sentence is the whole game. If you write a CLAUDE.md as if you’re programming a machine, you’ll get frustrated when the machine doesn’t comply. If you write it as context — the thing a thoughtful new teammate would want to read on day one — you’ll get something that works.

    This is the playbook I wish someone had handed me the first time I set one up across a real codebase. It’s grounded in Anthropic’s current documentation (linked throughout), layered with patterns I’ve used across a network of production repos, and honest about where community practice has outrun official guidance.

    If any of this ages out, the docs are the source of truth. Start there, come back here for the operator layer.


    The memory stack in 2026 (what CLAUDE.md actually is, and isn’t)

    Claude Code’s memory system has three parts. Most people know one of them, and the other two change how you use the first.

    CLAUDE.md files are markdown files you write by hand. Claude reads them at the start of every session. They contain instructions you want Claude to carry across conversations — build commands, coding standards, architectural decisions, “always do X” rules. This is the part people know.

    Auto memory is something Claude writes for itself. Introduced in Claude Code v2.1.59, it lets Claude save notes across sessions based on your corrections — build commands it discovered, debugging insights, preferences you kept restating. It lives at ~/.claude/projects/<project>/memory/ with a MEMORY.md entrypoint. You can audit it with /memory, edit it, or delete it. It’s on by default. (Anthropic docs.)

    .claude/rules/ is a directory of smaller, topic-scoped markdown files — code-style.md, testing.md, security.md — that can optionally be scoped to specific file paths via YAML frontmatter. A rule with paths: ["src/api/**/*.ts"] only loads when Claude is working with files matching that pattern. (Anthropic docs.)

    The reason this matters for how you write CLAUDE.md: once you understand what the other two are for, you stop stuffing CLAUDE.md with things that belong somewhere else. A 600-line CLAUDE.md isn’t a sign of thoroughness. It’s usually a sign the rules directory doesn’t exist yet and auto memory is disabled.

    Anthropic’s own guidance is explicit: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.

    Hold that number. We’ll come back to it.


    Where CLAUDE.md lives (and why scope matters)

    CLAUDE.md files can live in four different scopes, each with a different purpose. More specific scopes take precedence over broader ones. (Full precedence table in Anthropic docs.)

    Managed policy CLAUDE.md lives at the OS level — /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows. Organizations deploy it via MDM, Group Policy, or Ansible. It applies to every user on every machine it’s pushed to, and individual settings cannot exclude it. Use it for company-wide coding standards, security posture, and compliance reminders.

    Project CLAUDE.md lives at ./CLAUDE.md or ./.claude/CLAUDE.md. It’s checked into source control and shared with the team. This is the one you’re writing when someone says “set up CLAUDE.md for this repo.”

    User CLAUDE.md lives at ~/.claude/CLAUDE.md. It’s your personal preferences across every project on your machine — favorite tooling shortcuts, how you like code styled, patterns you want applied everywhere.

    Local CLAUDE.md lives at ./CLAUDE.local.md in the project root. It’s personal-to-this-project and gitignored. Your sandbox URLs, preferred test data, notes Claude should know that your teammates shouldn’t see.

    Claude walks up the directory tree from wherever you launched it, concatenating every CLAUDE.md and CLAUDE.local.md it finds. Subdirectories load on demand — they don’t hit context at launch, but get pulled in when Claude reads files in those subdirectories. (Anthropic docs.)

    A practical consequence most teams miss: in a monorepo, your parent CLAUDE.md gets loaded when a teammate runs Claude Code from inside a nested package. If that parent file contains instructions that don’t apply to their work, Claude will still try to follow them. That’s what the claudeMdExcludes setting is for — it lets individuals skip CLAUDE.md files by glob pattern at the local settings layer.

    If you’re running Claude Code across more than one repo, decide now whether your standards belong in project CLAUDE.md (team-shared) or user CLAUDE.md (just you). Writing the same thing in both is how you get drift.


    The 200-line discipline

    This is the rule I see broken most often, and it’s the rule Anthropic is most explicit about. From the docs: “target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.”

    Two things are happening in that sentence. One, CLAUDE.md eats tokens — every session, every time, whether Claude needed those tokens or not. Two, longer files don’t actually produce better compliance. The opposite. When instructions are dense and undifferentiated, Claude can’t tell which ones matter.

    The 200-line ceiling isn’t a hard cap. You can write a 400-line CLAUDE.md and Claude will load the whole thing. It just won’t follow it as well as a 180-line file would.

    Three moves to stay under:

    1. Use @imports to pull in specific files when they’re relevant. CLAUDE.md supports @path/to/file syntax (relative or absolute). Imported files expand inline at session launch, up to five hops deep. This is how you reference your README, your package.json, or a standalone workflow guide without pasting them into CLAUDE.md.

    See @README.md for architecture and @package.json for available scripts.
    
    # Git Workflow
    - @docs/git-workflow.md

    2. Move path-scoped rules into .claude/rules/. Anything that only matters when working with a specific part of the codebase — API patterns, testing conventions, frontend style — belongs in .claude/rules/api.md or .claude/rules/testing.md with a paths: frontmatter. They only load into context when Claude touches matching files.

    ---
    paths:
      - "src/api/**/*.ts"
    ---
    # API Development Rules
    
    - All API endpoints must include input validation
    - Use the standard error response format
    - Include OpenAPI documentation comments

    3. Move task-specific procedures into skills. If an instruction is really a multi-step workflow — “when you’re asked to ship a release, do these eight things” — it belongs in a skill, which only loads when invoked. CLAUDE.md is for the facts Claude should always hold in context; skills are for procedures Claude should run when the moment calls for them.

    If you follow these three moves, a CLAUDE.md rarely needs to exceed 150 lines. At that size, Claude actually reads it.


    What belongs in CLAUDE.md (the signal test)

    Anthropic’s own framing for when to add something is excellent, and it’s worth quoting directly because it captures the whole philosophy in four lines:

    Add to it when:

    • Claude makes the same mistake a second time
    • A code review catches something Claude should have known about this codebase
    • You type the same correction or clarification into chat that you typed last session
    • A new teammate would need the same context to be productive — Anthropic docs

    The operator version of the same principle: CLAUDE.md is the place you write down what you’d otherwise re-explain. It’s not the place you write down everything you know. If you find yourself writing “the frontend is built in React and uses Tailwind,” ask whether Claude would figure that out by reading package.json (it would). If you find yourself writing “when a user asks for a new endpoint, always add input validation and write a test,” that’s the kind of thing Claude won’t figure out on its own — it’s a team convention, not an inference from the code.

    The categories I’ve found actually earn their place in a project CLAUDE.md:

    Build and test commands. The exact string to run the dev server, the test suite, the linter, the type checker. Every one of these saves Claude a round of “let me look for a package.json script.”

    Architectural non-obvious. The thing a new teammate would need someone to explain. “This repo uses event sourcing — don’t write direct database mutations, emit events instead.” “We have two API surfaces, /public/* and /internal/*, and they have different auth requirements.”

    Naming conventions and file layout. “API handlers live in src/api/handlers/.” “Test files go next to the code they test, named *.test.ts.” Specific enough to verify.

    Coding standards that matter. Not “write good code” — “use 2-space indentation,” “prefer const over let,” “always export types separately from values.”

    Recurring corrections. The single most valuable category. Every time you find yourself re-correcting Claude about the same thing, that correction belongs in CLAUDE.md.

    What usually doesn’t belong:

    • Long lists of library choices (Claude can read package.json)
    • Full architecture diagrams (link to them instead)
    • Step-by-step procedures (skills)
    • Path-specific rules that only matter in one part of the repo (.claude/rules/ with a paths: field)
    • Anything that would be true of any project (that goes in user CLAUDE.md)

    Writing instructions Claude will actually follow

    Anthropic’s own guidance on effective instructions comes down to three principles, and every one of them is worth taking seriously:

    Specificity. “Use 2-space indentation” works better than “format code nicely.” “Run npm test before committing” works better than “test your changes.” “API handlers live in src/api/handlers/” works better than “keep files organized.” If the instruction can’t be verified, it can’t be followed reliably.

    Consistency. If two rules contradict each other, Claude may pick one arbitrarily. This is especially common in projects that have accumulated CLAUDE.md files across multiple contributors over time — one file says to prefer async/await, another says to use .then() for performance reasons, and nobody remembers which was right. Do a periodic sweep.

    Structure. Use markdown headers and bullets. Group related instructions. Dense paragraphs are harder to scan, and Claude scans the same way you do. A CLAUDE.md with clear section headers — ## Build Commands, ## Coding Style, ## Testing — outperforms the same content run together as prose.

    One pattern I’ve found useful that isn’t in the docs: write CLAUDE.md in the voice of a teammate briefing another teammate. Not “use 2-space indentation” but “we use 2-space indentation.” Not “always include input validation” but “every endpoint needs input validation — we had a security incident last year and this is how we prevent the next one.” The “why” is optional but it improves adherence because Claude treats the rule as something with a reason behind it, not an arbitrary preference.


    Community patterns worth knowing (flagged as community, not official)

    The following are patterns I’ve seen in operator circles and at industry events like AI Engineer Europe 2026, where practitioners share how they’re running Claude Code in production. None of these are in Anthropic’s documentation as official guidance. I’ve included them because they’re useful; I’m flagging them because they’re community-origin, not doctrine. Your mileage may vary, and Anthropic’s official behavior could change in ways that affect these patterns.

    The “project constitution” framing. Community shorthand for treating CLAUDE.md as the living document of architectural decisions — the thing new contributors read to understand how the project thinks. The framing is useful even though Anthropic doesn’t use the word. It captures the right posture: CLAUDE.md is the place for the decisions you want to outlast any individual conversation.

    Prompt-injecting your own codebase via custom linter errors. Reported at AI Engineer Europe 2026: some teams embed agent-facing prompts directly into their linter error messages, so when an automated tool catches a mistake, the error text itself tells the agent how to fix it. Example: instead of a test failing with “type mismatch,” the error reads “You shouldn’t have an unknown type here because we parse at the edge — use the parsed type from src/schemas/.” This is not documented Anthropic practice; it’s a community pattern that works because Claude Code reads tool output and tool output flows into context. Use with judgment.

    File-size lint rules as context-efficiency guards. Some teams enforce file-size limits (commonly cited: 350 lines max) via their linters, with the explicit goal of keeping files small enough that Claude can hold meaningful ones in context without waste. Again, community practice. The number isn’t magic; the discipline is.

    Token Leverage as a team metric. The idea that teams should track token spend ÷ human labor spend as a ratio and try to scale it. This is business-strategy content, not engineering guidance, and it’s emerging community discourse rather than settled practice. Take it as a thought experiment, not a KPI to implement by Monday.

    I’d rather flag these honestly than pretend they’re settled. If something here graduates from community practice to official recommendation, I’ll update.


    Enterprise: managed-policy CLAUDE.md (and when to use settings instead)

    For organizations deploying Claude Code across teams, there’s a managed-policy CLAUDE.md that applies to every user on a machine and cannot be excluded by individual settings. It lives at /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux and WSL), or C:\Program Files\ClaudeCode\CLAUDE.md (Windows), and is deployed via MDM, Group Policy, Ansible, or similar.

    The distinction that matters most for enterprise: managed CLAUDE.md is guidance, managed settings are enforcement. Anthropic is clear about this. From the docs:

    Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude’s behavior but are not a hard enforcement layer. — Anthropic docs

    If you need to guarantee that Claude Code can’t read .env files or write to /etc, that’s a managed settings concern (permissions.deny). If you want Claude to be reminded of your company’s code review standards, that’s managed CLAUDE.md. If you confuse the two and put your security policy in CLAUDE.md, you have a strongly-worded suggestion where you needed a hard wall.

    Building With Claude?

    I’ll send you the CLAUDE.md cheat sheet personally.

    If you’re in the middle of a real project and this playbook is helping — or raising more questions — just email me. I read every message.

    Email Will → will@tygartmedia.com

    The right mental model:

    Concern Configure in
    Block specific tools, commands, or file paths Managed settings (permissions.deny)
    Enforce sandbox isolation Managed settings (sandbox.enabled)
    Authentication method, organization lock Managed settings
    Environment variables, API provider routing Managed settings
    Code style and quality guidelines Managed CLAUDE.md
    Data handling and compliance reminders Managed CLAUDE.md
    Behavioral instructions for Claude Managed CLAUDE.md

    (Full table in Anthropic docs.)

    One practical note: managed CLAUDE.md ships to developer machines once, so it has to be right. Review it, version it, and treat changes to it the way you’d treat changes to a managed IDE configuration — because that’s what it is.


    The living document problem: auto memory, CLAUDE.md, and drift

    The thing that changed most in 2026 is that Claude now writes memory for itself when auto memory is enabled (on by default since Claude Code v2.1.59). It saves build commands it discovered, debugging insights, preferences you expressed repeatedly — and loads the first 200 lines (or 25KB) of its MEMORY.md at every session start. (Anthropic docs.)

    This changes how you think about CLAUDE.md in two ways.

    First, you don’t need to write CLAUDE.md entries for everything Claude could figure out on its own. If you tell Claude once that the build command is pnpm run build --filter=web, auto memory might save that, and you won’t need to codify it in CLAUDE.md. The role of CLAUDE.md becomes more specifically about what the team has decided, rather than what the tool needs to know to function.

    Second, there’s a new audit surface. Run /memory in a session and you can see every CLAUDE.md, CLAUDE.local.md, and rules file being loaded, plus a link to open the auto memory folder. The auto memory files are plain markdown. You can read, edit, or delete them.

    A practical auto-memory hygiene pattern I’ve landed on:

    • Once a month, open /memory and skim the auto memory folder. Anything stale or wrong gets deleted.
    • Quarterly, review the CLAUDE.md itself. Has anything changed in how the team works? Are there rules that used to matter but don’t anymore? Conflicting instructions accumulate faster than you think.
    • Whenever a rule keeps getting restated in conversation, move it from conversation to CLAUDE.md. That’s the signal Anthropic’s own docs describe, and it’s the right one.

    CLAUDE.md files are living documents or they’re lies. A CLAUDE.md from six months ago that references libraries you’ve since replaced will actively hurt you — Claude will try to follow instructions that no longer apply.


    A representative CLAUDE.md template

    What follows is a synthetic example, clearly not any specific project. It demonstrates the shape, scope, and discipline of a good project CLAUDE.md. Adapt it to your codebase. Keep it under 200 lines.

    # Project: [Name]
    
    ## Overview
    Brief one-paragraph description of what this project is and who uses it.
    Link to deeper architecture docs rather than duplicating them here.
    
    See @README.md for full architecture.
    
    ## Build and Test Commands
    - Install: `pnpm install`
    - Dev server: `pnpm run dev`
    - Build: `pnpm run build`
    - Test: `pnpm test`
    - Type check: `pnpm run typecheck`
    - Lint: `pnpm run lint`
    
    Run `pnpm run typecheck` and `pnpm test` before committing. Both must pass.
    
    ## Tech Stack
    (Only list the non-obvious choices. Claude can read package.json.)
    - We use tRPC, not REST, for internal APIs.
    - Styling is Tailwind with a custom token file at `src/styles/tokens.ts`.
    - Database migrations via Drizzle, not Prisma (migrated in Q1 2026).
    
    ## Directory Layout
    - `src/api/` — tRPC routers, grouped by domain
    - `src/components/` — React components, one directory per component
    - `src/lib/` — shared utilities, no React imports allowed here
    - `src/server/` — server-only code, never imported from client
    - `tests/` — integration tests (unit tests live next to source)
    
    ## Coding Conventions
    - TypeScript strict mode. No `any` without a comment explaining why.
    - Functional components only. No class components.
    - Imports ordered: external, internal absolute, relative.
    - 2-space indentation. Prettier config in `.prettierrc`.
    
    ## Conventions That Aren't Obvious
    - Every API endpoint validates input with Zod. No exceptions.
    - Database queries go through the repository layer in `src/server/repos/`. 
      Never import Drizzle directly from route handlers.
    - Errors surfaced to the UI use the `AppError` class from `src/lib/errors.ts`.
      This preserves error codes for the frontend to branch on.
    
    ## Common Corrections
    - Don't add new top-level dependencies without discussing first.
    - Don't create new files in `src/lib/` without checking if a similar 
      utility already exists.
    - Don't write tests that hit the real database. Use the test fixtures 
      in `tests/fixtures/`.
    
    ## Further Reading
    - API design rules: @.claude/rules/api.md
    - Testing conventions: @.claude/rules/testing.md
    - Security: @.claude/rules/security.md

    That’s roughly 70 lines. Notice what it doesn’t include: no multi-step procedures, no duplicated information from package.json, no universal-best-practice lectures. Every line is either a command you’d otherwise re-type, a convention a new teammate would need briefed, or a pointer to a more specific document.


    When CLAUDE.md still isn’t being followed

    This happens to everyone eventually. Three debugging steps, in order:

    1. Run /memory and confirm your file is actually loaded. If CLAUDE.md isn’t in the list, Claude isn’t reading it. Check the path — project CLAUDE.md can live at ./CLAUDE.md or ./.claude/CLAUDE.md, not both, not a subdirectory (unless Claude happens to be reading files in that subdirectory).

    2. Make the instruction more specific. “Write clean code” is not an instruction Claude can verify. “Use 2-space indentation” is. “Handle errors properly” is not an instruction. “All errors surfaced to the UI must use the AppError class from src/lib/errors.ts” is.

    3. Look for conflicting instructions. A project CLAUDE.md saying “prefer async/await” and a .claude/rules/performance.md saying “use raw promises for hot paths” will cause Claude to pick one arbitrarily. In monorepos this is especially common — an ancestor CLAUDE.md from a different team can contradict yours. Use claudeMdExcludes to skip irrelevant ancestors.

    If you need guarantees rather than guidance — “Claude cannot, under any circumstances, delete this directory” — that’s a settings-level permissions concern, not a CLAUDE.md concern. Write the rule in settings.json under permissions.deny and the client enforces it regardless of what Claude decides.


    FAQ

    What is CLAUDE.md? A markdown file Claude Code reads at the start of every session to get persistent instructions for a project. It lives in a project’s source tree (usually at ./CLAUDE.md or ./.claude/CLAUDE.md), gets loaded into the context window as a user message after the system prompt, and contains coding standards, build commands, architectural decisions, and other team-level context. Anthropic is explicit that it’s guidance, not enforcement. (Source.)

    How long should a CLAUDE.md be? Under 200 lines. Anthropic’s own guidance is that longer files consume more context and reduce adherence. If you’re over that, split with @imports or move topic-specific rules into .claude/rules/.

    Where should CLAUDE.md live? Project-level: ./CLAUDE.md or ./.claude/CLAUDE.md, checked into source control. Personal-global: ~/.claude/CLAUDE.md. Personal-project (gitignored): ./CLAUDE.local.md. Organization-wide (enterprise): /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux/WSL), or C:\Program Files\ClaudeCode\CLAUDE.md (Windows).

    What’s the difference between CLAUDE.md and auto memory? CLAUDE.md is instructions you write for Claude. Auto memory is notes Claude writes for itself across sessions, stored at ~/.claude/projects/<project>/memory/. Both load at session start. CLAUDE.md is for team standards; auto memory is for build commands and preferences Claude picks up from your corrections. Auto memory requires Claude Code v2.1.59 or later.

    Can Claude ignore my CLAUDE.md? Yes. CLAUDE.md is loaded as a user message and Claude “reads it and tries to follow it, but there’s no guarantee of strict compliance.” For hard enforcement (blocking file access, sandbox isolation, etc.) use settings, not CLAUDE.md.

    Does AGENTS.md work for Claude Code? Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it with @AGENTS.md at the top, then append Claude-specific instructions below.

    What’s .claude/rules/ and when should I use it? A directory of smaller, topic-scoped markdown files that can optionally be scoped to specific file paths via YAML frontmatter. Use it when your CLAUDE.md is getting long or when instructions only matter in part of the codebase. Rules without a paths: field load at session start with the same priority as .claude/CLAUDE.md; rules with a paths: field only load when Claude works with matching files.

    How do I generate a starter CLAUDE.md? Run /init inside Claude Code. It analyzes your codebase and produces a starting file with build commands, test instructions, and conventions it discovers. Refine from there with instructions Claude wouldn’t discover on its own.


    A closing note

    The biggest mistake I see people make with CLAUDE.md isn’t writing it wrong — it’s writing it once and forgetting it exists. Six months later it references libraries they’ve since replaced, conventions that have since shifted, and a team structure that has since reorganized. Claude dutifully tries to follow instructions that no longer apply, and the team wonders why the tool seems to have gotten worse.

    CLAUDE.md is a living document or it’s a liability. Treat it the way you’d treat a critical piece of onboarding documentation, because functionally that’s exactly what it is — onboarding for the teammate who shows up every session and starts from zero.

    Write it for that teammate. Keep it short. Update it when reality shifts. And remember the part nobody likes to admit: it’s guidance, not enforcement. For anything that has to be guaranteed, reach for settings instead.


    Sources and further reading

    Community patterns referenced in this piece were reported at AI Engineer Europe 2026 and captured in a session recap. They represent emerging practice, not Anthropic doctrine.

  • Hood Canal South: Potlatch State Park Spring Shellfish Season & Hoodsport Ace & Lumber Grand Opening (April 2026)

    Hood Canal South: Potlatch State Park Spring Shellfish Season & Hoodsport Ace & Lumber Grand Opening (April 2026)

    Monday regional beat — Hood Canal South (Belfair, Union, Hoodsport, Potlatch, Skokomish). If you live on the Olympic Peninsula, these are the two things worth your attention along US Hwy 101 this week.

    Potlatch State Park: Spring Low Tides and an Open Shellfish Season

    Potlatch State Park — about 12 miles north of Shelton on US Hwy 101, just north of Skokomish tribal lands — sits on one of the more productive shellfish beaches in Hood Canal. The park runs 5,700 feet of saltwater shoreline with more than a mile of tidelands that drop away at low tide into the kind of gravel-and-mud flats the state built its clam reputation on.

    Here’s the part peninsula residents already know but visitors miss: the recreational shellfish season at Potlatch is open from April 1 through May 31, 2026, per the Washington Department of Fish and Wildlife. Clams, mussels, and oysters are all in play, assuming you’ve got a current shellfish license and you’re checking your limits.

    Two non-negotiables before you go:

    • Call the Washington Department of Health Shellfish Safety Hotline at 1-800-562-5632 (or check the DOH shellfish safety page) before you harvest. Biotoxin closures can flip a beach overnight, and Hood Canal is one of the areas watched closely.
    • Display a Discover Pass on your vehicle. Potlatch is a Washington State Park — day-use requires it, no exceptions.

    If you’ve never tidepooled this stretch, the window is narrow and the reward is big. Check your local tide table, pack a bucket and gloves, and plan to be down on the flats an hour before dead low. The Skokomish estuary is just to the south, and the wildlife traffic along that shoreline during a minus tide is worth the drive by itself.

    Hoodsport Ace & Lumber: Grand Opening Saturday, April 25

    If you’ve driven through Hoodsport in the last year, you’ve probably noticed a new hardware store quietly taking shape at 150 N Lake Cushman Road. That’s Hoodsport Ace & Lumber, and this Saturday — April 25, 2026 — is the official grand opening.

    Here’s what’s on the day:

    • Date: Saturday, April 25, 2026
    • Time: 8:00 AM to 4:00 PM (ribbon cutting at 8:00 AM sharp)
    • Location: 150 N Lake Cushman Road, Hoodsport, WA 98548
    • Cost: Free
    • What to expect: Hourly deals, giveaways, in-store specials

    The store has been operating informally for about a year while the team ironed things out, and management has flagged that an on-site rental center is coming later this year — a legitimately useful addition for Lake Cushman property owners who have, until now, been driving to Shelton or Belfair for weekend projects.

    For a small peninsula town like Hoodsport, a fully stocked hardware and lumber yard that isn’t a 30-minute drive changes the weekend math on almost every home project. If you live anywhere from Potlatch to Lake Cushman and you’ve been waiting for this one to officially open, Saturday is the day.

    Why This Week, Why Hood Canal South

    The Monday rotation focuses on Hood Canal South because it’s the stretch of 101 most people blow past on the way somewhere else — and it’s the stretch where the best peninsula intel tends to hide in plain sight. Shellfish season opening alongside a new hardware store in the same town is exactly the kind of weekend the south end quietly puts together without a press release.

    Next Monday’s Hood Canal South beat will likely circle back to Hama Hama Oyster Rama (the April 18-19 event) for a retrospective if anything newsworthy came out of it. For now — Potlatch tide tables and a Saturday ribbon cutting.

    Sources & Further Reading