DEV Community: Cogweald

AI-generated content still needs to be discoverable

Cogweald — Sat, 10 Oct 2026 07:11:47 +0000

Creating content is only the first step. If a world updates every day but nobody can find it, the system is quietly computing for no one.

When a public Cogweald world publishes a new chapter, it sends the chapter URL, story page, and homepage to IndexNow. When a world changes from private or unlisted to public, the whole content tree can be submitted as newly discoverable.

This is useful for products that continuously create new pages. Instead of waiting for the next natural crawl, the system sends an update signal when content becomes public.

There is an important policy distinction: unlisted does not mean “less important public.” It means link-only, so it should not be submitted for search indexing.

AI content distribution is not just a marketing task to add at the end. Visibility, canonical URLs, RSS, sitemaps, and indexing policy belong in the domain model from the beginning.

Public, unlisted, and private are not three checkboxes

Cogweald — Wed, 07 Oct 2026 00:24:04 +0000

Content platforms often treat visibility as a UI field and implement the rules separately on every page. That eventually creates bugs: a story appears on the homepage but its shared link fails, or private content becomes visible to search engines.

Cogweald treats visibility as part of the read model:

Public: listed in the catalogue and readable.
Unlisted: not listed in the catalogue, but readable by anyone with the link.
Private: readable only by the owner.

The same meaning must apply to SSR pages, archives, chapter routes, RSS, Open Graph images, and Explore queries. Forgetting the rule on any one surface creates an information boundary bug.

A practical testing reminder: do not only test whether a button is hidden. Test every possible entry point that can retrieve the data.

Visibility is domain policy, not a presentation detail.

Cache invalidation for generated content cannot be an act of faith

Cogweald — Tue, 06 Oct 2026 07:49:46 +0000

AI content is generated dynamically, but reader-facing pages can still be highly cacheable. The two ideas are compatible if you know exactly when the cache must be invalidated.

Cogweald uses an appropriate ISR strategy for public story pages, archives, the homepage, and the library. After a chapter is successfully persisted, the cron route revalidates the relevant paths so the next reader sees the new content instead of waiting for a passive expiry.

There is an easy-to-miss detail: only a fully successful domain operation should trigger revalidation. If model generation succeeds but persistence fails, the page must not look like a chapter was published.

Cache invalidation is difficult not because the API is complicated, but because it must match the consistency semantics of your data.

When your AI content has a publishing concept, design generation, persistence, notifications, and cache updates as one event flow.

Keep AI services out of Client Components

Cogweald — Mon, 05 Oct 2026 14:30:53 +0000

This is not just a Next.js style preference. It is a security boundary.

Cogweald keeps OpenAI, Supabase service-role access, billing, and the simulation engine in server-only code. Client Components can call controlled server actions or route handlers, but they never import those services directly.

The reasons are practical:

API keys must not enter the browser bundle.
A service-role client must not be exposed to users.
Chapter generation needs authorization and state validation.
Billing actions must run in a trusted server context.

AI apps often put sensitive calls in the browser just to make the first button work, then try to repair the boundary after deployment. A better approach is to establish it in the import graph from the beginning: which modules are server-only, and which data is safe to send to the client?

A feature can be finished later. Secrets should never be shipped first.

Limits are not anti-AI. They keep the system alive.

Cogweald — Sun, 04 Oct 2026 11:56:38 +0000

If an agent can create unlimited worlds, characters, and images, a product quickly faces two problems: unpredictable costs and no responsible resource boundary.

Cogweald treats plan limits as domain rules, not as text on a pricing page. maxWorlds, maxChapters, maxCharacters, and maxCoverGenerations are enforced on the server. Disabling a frontend button is not enough.

Limits also need to be checked before a state transition. When a free world reaches its chapter cap, the system pauses it and notifies the creator instead of letting the next cron run discover the problem too late.

A good quota system does more than reject requests. It defines:

When to reject
When to pause
How the user can recover
What happens to data that already exists

“Unlimited” is attractive product copy. In a real AI system, predictability is often more valuable.

An agent needs to create new entities to truly grow

Cogweald — Thu, 24 Sep 2026 06:51:47 +0000

An agent that can only modify a fixed set of rows has a hard time producing an open-ended system.

Cogweald does not completely predefine the cast of every world. The model can introduce a new character in a chapter, and the application stores that character with added_by = 'llm' so future chapters can use it.

The important part is not that AI can insert a row. It is provenance.

Every entity should have an answer to “where did this come from?” It may have been created by the creator, introduced by the LLM, or synchronized from an external tool. Once an agent can create data, provenance affects review, debugging, UI decisions, and future deletion strategies.

Open-ended generation needs two things:

An extensible domain model
A data model that tracks origin

Without provenance, an autonomous system eventually struggles to answer a basic question: why does this thing exist?

Give the AI suggestions, not a script

Cogweald — Tue, 22 Sep 2026 23:49:44 +0000

If a user can specify exactly what must happen in the next chapter, the AI becomes a writing tool and the world stops being autonomous.

Cogweald treats creator hints as wishes from a producer, not hard commands. A creator can suggest a direction, while the model can mark the hint as followed, delayed, twisted, or ignored and explain its decision.

This preserves two important things: human intent and agent judgment.

It also creates a more interesting product interaction. The creator is not clicking buttons to control every plot point. They are watching a system with its own logic respond to a suggestion. The hint becomes part of long-term state and can have consequences later.

For other agent products, this suggests a useful pattern: model human input as a preference, constraint, or hypothesis instead of treating every message as the highest-priority command.

An agent with a real point of view must be able to say, “Not yet.”

An offline cron can be a strong product decision

Cogweald — Tue, 22 Sep 2026 00:54:17 +0000

Not every AI product needs to generate something in real time.

Cogweald advances each world once per day instead of generating the next chapter when a reader opens the page. That choice improves three things at once: user experience, cost control, and content consistency.

Readers know that new content arrives on a predictable cadence instead of seeing different versions generated on demand. The system can run during off-peak hours. A model failure does not block the reading experience.

More importantly, asynchronous generation makes “the world keeps running while you are away” part of the product experience. The user is not operating a tool; they are checking in on a system with its own rhythm.

Teams often treat real-time as the default answer. For some AI workflows, latency is not a flaw. It is part of the pacing, reliability model, and cost model.

Does the feature you are building really need to be real time?

One world, one LLM call

Cogweald — Mon, 21 Sep 2026 01:49:57 +0000

AI product costs often become unpredictable not because the model is too expensive, but because the architecture calls the model too many times for the same operation.

Cogweald intentionally keeps chapter generation to one LLM call per world. That call produces the content, summary, time span, character updates, thread updates, and long-term facts together.

This is not about cramming everything into one prompt. It starts with designing an output contract so one reasoning result can become one complete domain event.

The benefits are straightforward:

Costs are easier to estimate.
Each chapter has one source of truth for its decisions.
A summary model cannot contradict a content model.
Retry semantics are easier to reason about.
Token usage is easier to observe.

Single-call is not always the right answer. Workflows that need multiple validation stages or tool interactions may need multiple calls. Before splitting, ask whether those calls truly need different reasoning boundaries.

A cron job is not just “ask the model to run”

Cogweald — Sun, 20 Sep 2026 06:53:35 +0000

When an AI job runs once a day, it is easy to underestimate the distributed-systems problems hiding underneath.

What if the scheduler retries? What if two workers claim the same world? What if the model succeeds but the database connection drops before the chapter is stored?

Cogweald treats daily advancement as a claim-based transaction flow. A world’s last_tick_at acts as both the schedule marker and the claim token. A worker must successfully claim the tick before it is allowed to generate a chapter.

That small design prevents one of the most dangerous failure modes: cron jitter producing two chapters for the same world on the same day.

Reliability in AI systems often comes less from a better prompt and more from ordinary-looking conditional database updates.

Once an agent can change the world on its own, design its state transitions with the same care you would use for a payment flow.

Autonomous agents need guardrails, not line-by-line scripts

Cogweald — Fri, 18 Sep 2026 00:10:25 +0000

Autonomous does not mean uncontrollable.

Cogweald’s model can decide what happens next in a world. It cannot change the database schema, bypass authorization, arbitrarily rewrite published content, or turn unvalidated text directly into system state.

The guardrails live outside the model:

Output must match a structured schema.
World state can only change through the server-side persistence layer.
Character and thread transitions must follow defined rules.
A failed generation must not commit half of a world update.
Every tick has a claim guard to prevent duplicate execution.

The model gets creative freedom. The system owns consistency.

This is one of my favorite agent design principles: do not describe every rule in a prompt. If code can guarantee something reliably, let code guarantee it. Give the model the decisions that actually require semantic judgment.

A plot thread is really a state machine

Cogweald — Wed, 16 Sep 2026 23:57:41 +0000

“Let the AI advance the story” sounds exciting, but without a state model, every chapter quickly starts inventing the same problems again.

Cogweald models long-running plot lines as story threads. Each thread has a title, description, status, and timestamps. Its status can be active, resolved, or abandoned.

When a chapter is generated, the model does not only return prose. It also returns thread updates: which thread advanced, which one was resolved, and whether a new one should be opened. The application applies those decisions to the database and provides the updated state to the model next time.

This turns continuity from a hope into an observable and verifiable state transition.

The same pattern works for any agent that needs long-term planning:

An unfinished refactor for a coding agent
An unverified hypothesis for a research agent
A customer risk for a success agent
A quest line for a game agent

If an agent needs to remember what is still unfinished across multiple runs, it probably deserves a state machine.