Smeldr

Typed backend for decisions, tasks, and content that people and AI agents write to at the same time. Every item has an enforced lifecycle: a Decision moves proposed → ratified only when the right role approves it. Every relation between items is checked, not assumed: a background sweep flags connections that no longer hold.

A real decision, from this repo's own history:

{
  "decision_number": "D59",
  "state": "ratified",
  "body": "Goals are places: new `contains` RelationStore kind (working name) gives Smeldr a first-class, user-defined taxonomy... Any item relates to a Goal via the new kind; the taxonomy is user/org-defined since Goals are already freely created, not a fixed enum.",
  "next_eval_at": null
}

Smeldr's own architecture decisions are tracked as Decision items and ratified the same way any Smeldr-hosted decision is. Full text: DECISIONS.md (D59); excerpted above for length.

cd example/server
SECRET=changeme ENABLE_ORCHESTRATION=1 go run .

Start a chat with your favorite agent, create content together and then...

...build and publish websites. Edit sections, upload images and manage access directly in chat. Hook up your workflow states to AI actions.

...schedule, change, delete posts on X, Mastodon or LinkedIn

...build apps and manage data and automate workflows

...manage multiple agents to react to signals with the built-in agent runtime

...track decisions with a freshness cycle: propose, ratify, re-evaluate, so nothing silently goes stale

Or coordinate your entire pipeline and automated workflow, AI actions and human review included.

Directly from chat.

v1.145.0 — stable. Public APIs are stable within v1. See CHANGELOG.md.

30-second start

git clone https://github.com/smeldr/core
cd core
cd example/blog
go run .
# open http://localhost:8080

Generic server (no custom content types)

example/server is a deployable binary with no hard-coded Go content types — define everything at runtime via MCP:

cd example/server
SECRET=changeme go run .

Optional subsystems are gated by environment variables (ENABLE_TOKENS, ENABLE_GOVERNANCE, ENABLE_RELATIONS, ENABLE_DYNAMIC_CONTENT, ENABLE_BLOCKS, ENABLE_MEDIA, ENABLE_SOCIAL, ENABLE_WEBHOOKS, ENABLE_PROVENANCE, ENABLE_STRUCTURAL_SWEEP, ENABLE_AGENTS, OAUTH_ISSUER). Set any to a non-empty value to enable that subsystem. See example/server/main.go for the full variable reference and wiring order.

What Smeldr gives you

Content

• Full CRUD — create, update, publish, archive, and delete through a single Module[T]
• Draft-safe lifecycle — drafts return 404 to guests; only Published content is visible
• Draft preview — share a signed ?preview=<token> URL to let reviewers see a draft without logging in
• Scheduled publishing — set a future ScheduledAt; Smeldr transitions to Published automatically
• Content negotiation — one endpoint serves JSON, HTML, or Markdown based on Accept

AI-native

• AI indexing — /llms.txt compact index, /llms-full.txt Markdown corpus, and per-item /aidoc endpoints
• MCP integration — connect AI agents to read and write content via the Model Context Protocol

Auth & security

• Role-based auth — Guest → Author → Editor → Admin enforced per-module, per-operation
• Cookie compliance — /.well-known/cookies.json declares cookie categories for GDPR tooling
• Security headers — CSP, HSTS, X-Frame-Options wired in one middleware call

Discovery

• Structured data (JSON-LD) — Article, Product, FAQ, and more emitted in every page <head>
• Event-driven sitemap — regenerated on publish, update, and delete; no cron job required
• Open Graph — og:title, og:description, og:image meta tags for social link previews
• Twitter Cards — twitter: meta tags with summary and summary_large_image support
• RSS feed — per-module feed at /{prefix}/feed.xml plus a global aggregate at /feed.xml

Infrastructure

• Graceful shutdown — drains in-flight requests before exiting on SIGINT/SIGTERM
• Log capture — opt-in app.CaptureLogs() keeps recent errors in memory and serves them at GET /_logs (Admin) for live debugging — over plain HTTP, so it works even when MCP is down

Installation

go get smeldr.dev/core

Requires Go 1.26+. No other dependencies.

Databases. State flows (transition rules and role gates, Locked states, SuppressesSignals, async triggers and ConflictPolicy) are enforced on SQLite and on Postgres alike. From v1.118.0 that includes Postgres through smeldr.dev/core/pgx, where a flow used to be stored and never consulted: upgrading can refuse transitions that passed unchecked, so read the upgrade note in State flows.

---

Minimal example

Define a content type, wire it, run it.

package main

import (
	"log"

	"smeldr.dev/core"
)

type Post struct {
	smeldr.Node
	Title string `smeldr:"required,min=3" json:"title"`
	Body  string `smeldr:"required"       json:"body"`
}

func (p *Post) Head() smeldr.Head {
	return smeldr.Head{
		Title:       p.Title,
		Description: smeldr.Excerpt(p.Body, 160),
	}
}

func (p *Post) Markdown() string { return p.Body }

func main() {
	repo := smeldr.NewMemoryRepo[*Post]()
	m := smeldr.NewModule((*Post)(nil), // nil pointer — type parameter inferred, no allocation
		smeldr.At("/posts"),
		smeldr.Repo(repo),
		smeldr.Auth(smeldr.Read(smeldr.Guest), smeldr.Write(smeldr.Author)),
	)
	app := smeldr.New(smeldr.MustConfig(smeldr.Config{
		BaseURL: "http://localhost:8080",
		Secret:  []byte("change-this-secret-in-production"),
	}))
	app.Content(m)
	if err := app.Run(":8080"); err != nil {
		log.Fatal(err)
	}
}

Routes: GET /posts, GET /posts/{slug}, POST /posts, PUT /posts/{slug}, PATCH /posts/{slug}, DELETE /posts/{slug}, GET /sitemap.xml. Draft posts return 404 for guests.

---

Full feature showcase

Same content type. Add options — each line unlocks a production feature.

m := smeldr.NewModule((*Post)(nil),
	smeldr.At("/posts"),
	smeldr.Repo(smeldr.NewMemoryRepo[*Post]()),
	smeldr.Auth(smeldr.Read(smeldr.Guest), smeldr.Write(smeldr.Author)),
	smeldr.SitemapConfig{ChangeFreq: smeldr.Weekly, Priority: 0.8}, // /posts/sitemap.xml
	smeldr.Social(smeldr.OpenGraph, smeldr.TwitterCard),              // og: and twitter: meta tags
	smeldr.AIIndex(smeldr.LLMsTxt, smeldr.LLMsTxtFull, smeldr.AIDoc), // /llms.txt + /posts/{slug}/aidoc
	smeldr.Feed(smeldr.FeedConfig{Title: "My Blog"}),               // /posts/feed.xml + /feed.xml
	smeldr.Templates("templates/posts"),                           // HTML at Accept: text/html
	smeldr.On(smeldr.AfterPublish, func(_ smeldr.Context, p *Post) error {
		log.Printf("published: %s", p.Slug) // fires on publish and scheduled→Published
		return nil
	}),
)

Three runnable examples are in example/:

• example/blog — devlog with seeded posts, RSS, AI indexing, and scheduled publishing
• example/api — headless JSON API with role-based auth and a redirect manifest
• example/docs — documentation site with AI indexing, /llms.txt, and AIDoc endpoints

Each runs with: cd example/blog && go run .

---

Reference

Full API reference: REFERENCE.md
Self-hosting (release binaries, config, backup/restore): SELF_HOSTING.md
Web docs: smeldr.dev/docs

For full token management reference (create, list, revoke) see REFERENCE.md — Token management.
For draft preview tokens see REFERENCE.md — Draft preview.

---

License

AGPL v3 — free for individuals, open source projects, and companies building their own sites. A commercial license will be available for organisations running Smeldr as a hosted service. See COMMERCIAL.md.