AGENTS.md — OWN-01

Project

OWN-01 explores a sovereign, human-scale social web built from personal websites, ordinary HTTP, files, links, and optional hypermedia interactions.

The goal is not to build a decentralized social-media platform.

The goal is to explore what becomes possible when:

• a person owns their web presence,
• files are the durable artifact,
• HTTP is the interaction layer,
• HTML is a first-class interchange format,
• social interaction happens between independently owned sites,
• software remains replaceable,
• and participation stays intentionally small-scale.

Think:

A person has a place on the Web. That place can do whatever they want. Sites can choose to interact.

Context

OWN-01 is part of cygnus_x1/labs.

Related experiments:

• KSN-01 — persistent personal links and annotations over arbitrary webpages
• STN-01 — direct person-to-person streaming / presence experiments
• OWN-01 — sovereign personal sites interacting through hypermedia

Do not assume these experiments must converge into one application.

They may share protocols, conventions, or code where useful.

Principles

Prefer the Web itself over application architecture.

In priority order:

1. HTML
2. CSS
3. HTTP
4. Files
5. Browser APIs
6. Small amounts of plain JavaScript
7. Lightweight hypermedia helpers where they materially simplify things
8. Server-side code only when required
9. Infrastructure only when the experiment proves it needs infrastructure

Avoid complexity that exists only because modern web development commonly uses it.

Specifically

Prefer:

• static files
• Markdown
• semantic HTML
• links and forms
• native browser controls
• Caddy
• plain JavaScript
• Alpine.js for small declarative client state
• htmx for hypermedia-driven HTTP interaction
• Flask under /cgi-bin for small server-side experiments
• Makefiles / Maskfiles
• standard protocols
• readable source
• curl-debuggable endpoints

Avoid by default:

• React
• Vue
• Angular
• SPA architecture
• client-side routing
• bundlers
• transpilers
• Node/npm dependency trees
• virtual DOMs
• GraphQL
• application databases
• ORM layers
• centralized identity systems
• telemetry
• analytics
• recommendation algorithms
• engagement mechanics

None of these are absolutely prohibited.

They must earn their way into the experiment.

Architectural Bias

Start with documents.

A typical experiment should be able to begin as:

OWN-01/
├── README.md
├── index.html
├── style.css
└── app.js

Add server behavior only when needed:

/cgi-bin/own/*

A useful mental model is:

personal site
    |
    +-- files
    +-- links
    +-- forms
    +-- HTTP
    +-- optional client behavior
    |
    +----> another independently owned site

HTTP should be the seam between independently replaceable pieces.

Hypermedia

OWN-01 should investigate hypermedia-driven interaction seriously.

htmx is appropriate when it lets HTML express an interaction more directly than custom JavaScript.

For example, prefer:

<button
  hx-post="/cgi-bin/rsvp"
  hx-target="#rsvp-status">
  Going
</button>

with a server response like:

<p id="rsvp-status">You're going.</p>

over:

fetch JSON
→ parse JSON
→ update client state
→ render template
→ mutate DOM

when the HTML response is the actual thing the user needs.

Do not use htmx merely because it is available.

Ordinary links and forms remain preferable when they are sufficient.

Client-Side State

Use plain browser APIs first.

For small declarative state, Alpine.js is acceptable.

Examples:

• toggles
• local visibility state
• temporary selections
• small menus
• local filtering
• transient UI state

Do not turn Alpine into an application architecture.

Persistent or shared state should normally have an obvious representation outside the JavaScript runtime.

Files as Durable State

Where practical, represent persistent state as understandable files.

Examples:

guestbook/
  2026-09-03T181203Z-anna.md

rsvp/
  anna.yaml
  mitch.yaml

friends/
  anna.txt
  mitch.txt

annotations/
  <url-hash>.json

Prefer formats humans can inspect, copy, archive, version, and migrate.

A database may eventually become justified, but it is not the default.

Candidate Experiments

OWN-01 may explore things such as:

• guestbooks
• personal walls
• friend-only comments
• reactions between personal sites
• Webrings
• personal inboxes
• "send this to a friend"
• shared/private pages
• small collaborative documents
• /now pages
• personal status fragments
• friend dashboards
• RSVPs
• photo sharing
• recommendations
• annotations
• shared playlists
• small multiplayer toys
• personal presence
• site-to-site discovery
• identity based on domains or URLs
• signed messages
• selective trust relationships

Do not implement all of these.

Each should begin as an independent experiment.

Social Model

Do not assume:

• infinite audiences
• follower counts
• public engagement metrics
• global discovery
• virality
• ranking algorithms
• feeds optimized for attention
• centralized moderation
• universal schemas

Assume instead:

• small numbers of known people
• explicit trust
• deliberate following
• direct links
• pull over push where reasonable
• local control
• heterogeneous websites
• different people exposing different capabilities

A person's site does not need to conform to a global profile schema.

One site may expose:

/now
/photos
/garage
/friends

another:

/work
/music
/events

and another may expose nothing except a single HTML page.

Interoperability should happen through protocols and affordances, not identical page structures.

Discovery

Prefer existing Web mechanisms before inventing new ones.

Investigate things such as:

• <link>
• rel=
• canonical URLs
• /.well-known/
• HTTP headers
• RSS / Atom
• WebFinger where appropriate
• content negotiation where useful
• ordinary hyperlinks

Any new OWN-01 convention should be:

• small,
• inspectable,
• optional,
• versionable,
• and easy to implement without the rest of OWN-01.

Identity

A URL or domain should be considered a strong candidate for primary identity.

Avoid creating a centralized OWN-01 account system.

Possible future experiments may involve:

• domain ownership
• public keys
• signed requests
• signed documents
• capability URLs
• mutual trust lists

Do not design a complete identity protocol prematurely.

Privacy

Default to explicit, understandable boundaries.

Prefer:

• public
• private
• explicitly shared with known people

over complex visibility models.

Do not add telemetry.

Do not add tracking pixels.

Do not create shadow profiles.

Do not centralize interaction data merely for convenience.

Local / Public Parity

The experiment should run with minimal surprise on both macOS and NixOS.

Prefer the existing cygnus_x1 conventions:

• Caddy
• site.caddy
• Makefile
• Maskfile
• Flask
• gunicorn
• standard CLI tools

Avoid environment-specific behavior where practical.

Local and public routing should remain as similar as possible.

Dependencies

Dependencies should be:

• few,
• explicit,
• pinned where practical,
• understandable,
• replaceable.

Vendoring a small browser library is often preferable to introducing an npm toolchain.

If using Alpine.js or htmx, prefer a simple checked-in copy under a shared static directory unless there is a compelling reason not to.

Build System

There should be no build system unless something actually requires one.

A browser should ideally be able to consume the source files directly.

Do not introduce:

• Vite
• webpack
• Rollup
• Babel
• TypeScript compilation

merely for project convention.

JavaScript

Use modern browser JavaScript.

Prefer:

document.querySelector()
addEventListener()
fetch()
customElements.define()

over abstractions that obscure browser behavior.

Keep state local and explicit.

Favor code that can be understood by reading one file.

HTML

Prefer semantic HTML.

Use native elements when available, including:

• <dialog>
• <details>
• <summary>
• <form>
• <fieldset>
• <legend>
• <button>
• <output>
• <progress>

Do not recreate native browser functionality unnecessarily.

Progressive enhancement is preferred.

A page should remain meaningful when JavaScript fails whenever reasonably possible.

CSS

Prefer ordinary CSS.

Use modern platform capabilities where useful:

• custom properties
• nesting
• container queries
• :has()
• logical properties
• grid
• flexbox

Avoid CSS frameworks by default.

Server Behavior

Server endpoints should remain small.

Prefer:

GET  /cgi-bin/own/foo
POST /cgi-bin/own/foo

returning:

• HTML
• plain text
• JSON only when the data itself is the useful representation

Keep endpoints easy to exercise with:

curl

Failure Modes to Avoid

Watch for OWN-01 accidentally becoming:

• a social-media platform
• a framework
• a protocol suite
• an identity provider
• an npm project
• a React replacement
• a distributed database project
• ActivityPub implementation work without a concrete need
• infrastructure looking for a use case

When this happens, reduce scope.

Design Test

For any proposed feature, ask:

1. Could this simply be a file?
2. Could this simply be a link?
3. Could this simply be a form?
4. Could the server return HTML directly?
5. Could plain JavaScript handle the behavior?
6. Is the dependency making the system materially simpler?
7. Could another person implement the protocol without using our software?
8. Could the files survive if all OWN-01 code disappeared?

If the answers point toward a simpler implementation, use it.

North Star

OWN-01 should produce experiments where the durable pieces are ordinary Web artifacts and the software is merely an interpreter.

The desired end state is not:

everyone joins OWN-01.

It is:

people own places on the Web, those places can interact, and no particular software implementation is required for participation.