Plan chan.dev for agent-friendly HTML-first/HATEOAS architecture

[chantastic]

Summary

Rework chan.dev toward an HTML-first, HATEOAS-friendly architecture so both humans and agents can navigate and operate the site with minimal client-side assumptions.

This repo is already close: most public pages are server-rendered Astro documents with stable URLs. The opportunity is to make the app-ish areas, search flows, and future mutations follow a stricter HTML contract.

Why

Agents perform better when:

• important state is represented by URLs
• actions are expressed as links and forms
• server responses return the next useful document or fragment
• markup is semantic and structurally consistent across sections
• progressive enhancement is layered on top of a working HTML baseline

This is a better fit for Astro than adding more client-state complexity.

Current repo shape

Good foundations:

• Public content is already mostly document-first: src/pages/index.astro, src/pages/[post_slug].astro, collection routes, layouts, and content collections.
• Route structure is understandable and mostly stable.
• There are only a few clearly interactive surfaces today.

Notable pressure points:

• src/pages/search.astro is a JS widget shell rather than an HTML-first search experience.
• src/pages/dashboard/* is where server-driven application flows will matter most.
• Future tools/utilities risk becoming ad hoc UI islands unless we set conventions now.

Goals

1. Every important user action should work through plain HTML first.
2. The next valid actions in a flow should be discoverable from the current response.
3. URLs should represent resource identity and major application state.
4. HTMX, if used, should enhance existing link/form flows instead of replacing them.
5. Agents should be able to identify key resources and actions from stable markup conventions.

Non-goals

• Rewriting the content side of the site into an SPA.
• Introducing custom JS state machines where server-rendered HTML would suffice.
• Replacing all JSON endpoints; some machine-focused JSON mirrors may still be useful.

Proposed architecture

1. Keep content pages document-first

Leave posts, lessons, uses, projects, recipes, talks, and similar public content as normal Astro documents unless there is a strong reason not to.

2. Make app-like areas resource-oriented

For interactive sections, use canonical resource routes:

• /dashboard/habits
• /dashboard/habits/new
• /dashboard/habits/:id
• /dashboard/habits/:id/edit
• /dashboard/metadata
• /dashboard/metadata/new

General rule:

• GET returns navigable HTML documents or HTML fragments.
• POST performs mutations and redirects to the canonical next page, or returns a useful updated fragment when progressively enhanced.

3. Treat links/forms as the primary API

Use real anchors and forms for:

• navigation
• filtering
• create/update/delete actions
• toggles when possible
• confirmation steps

Avoid JS-only controls when the same operation can be expressed as a form or link.

4. Standardize response patterns

After mutation:

• redirect to the resource page or index when full-page navigation is expected
• return the updated list/item/flash region when HTMX is enhancing the interaction

Errors should render in HTML near the form fields or affected region, not as opaque transport errors.

5. Use HTMX only as progressive enhancement

If HTMX is introduced:

• forms/links must still work without it
• server endpoints should return meaningful HTML partials
• prefer simple swaps over clever client orchestration
• avoid introducing parallel client-side state that disagrees with the server

Markup conventions for agent effectiveness

Adopt stable, repeated HTML conventions across all app surfaces.

Structural conventions

• Use semantic landmarks: main, nav, section, header, footer, aside
• Use real lists and tables for collections
• Use headings that accurately describe the current resource or action
• Use explicit labels for all fields and buttons

Stable identifiers

Add durable handles to meaningful regions and actions, for example:

• id="habit-list"
• data-resource="habit"
• data-resource-id="..."
• data-action="edit"
• data-action="delete"
• aria-label="Delete habit Sleep by 10pm"

These should be used as a stable contract for both testing and agent navigation, not for styling hacks.

Naming consistency

Use the same labels everywhere for equivalent actions:

• New
• Edit
• Delete
• Archive
• Publish
• Save
• Cancel

Do not vary labels casually (Remove, Trash, Discard, etc.) unless the actions are genuinely different.

Search plan

Rework src/pages/search.astro so there is an HTML-first search experience.

Target behavior:

• GET /search renders the search form and optionally featured suggestions.
• GET /search?q=... renders plain HTML results.
• Pagefind or another JS enhancement can still be layered on top for richer UX.

This gives agents and no-JS users a stable search flow.

Route categories

Stay mostly as-is

• public content collections
• individual content pages
• feeds and share pages that are already document-oriented

Prioritize for HTML-first rework

• src/pages/search.astro
• src/pages/dashboard/index.astro
• src/pages/dashboard/**
• any future utilities that support creating, editing, filtering, or reviewing data

Consider fragment endpoints for enhancement

• list regions
• flash message regions
• inline edit forms
• filtered results

These should still map cleanly to canonical full-page routes.

Suggested implementation phases

Phase 1: conventions and base contract

• Write an AGENTS.md section for route semantics, mutation patterns, and markup conventions.
• Define resource/action attribute conventions.
• Decide where HTML fragments live and how they map to full-page routes.

Phase 2: search

• Convert /search into a real HTML-first search endpoint.
• Keep JS enhancement optional.
• Ensure result items have consistent structure and clear links.

Phase 3: dashboard and internal tools

• Refactor dashboard flows around resource routes and forms.
• Add clear success/error rendering.
• Ensure create/edit/delete operations produce useful next-state HTML.

Phase 4: progressive enhancement

• Add HTMX selectively where interaction latency or page refreshes feel unnecessarily heavy.
• Favor a few predictable patterns over broad HTMX sprawl.

Phase 5: machine-readable mirrors where justified

• Add JSON endpoints only when they provide clear value for bulk/programmatic use.
• Keep HTML as the primary interaction surface.

Acceptance criteria

• A user or agent can complete key flows using links and forms alone.
• Interactive routes expose canonical URLs for resources and edit/create states.
• Search works without client-side JS.
• Mutation responses always lead to a useful next page or updated HTML region.
• Equivalent UI actions use consistent labels and markup patterns across the site.
• App surfaces include stable identifiers for key resources and actions.

Open questions

• Should authenticated dashboard tools remain private utility pages, or become a more formal internal app surface with shared patterns/components?
• Do we want server-rendered search results from Astro content directly, or an HTML wrapper around the Pagefind index?
• How much fragment infrastructure is worth introducing before there are more active app workflows?

Notes

The main design principle here is not “use HTMX everywhere.” It is “make the site legible, navigable, and operable through HTML.” If that contract is strong, HTMX becomes an implementation detail rather than the architecture.