System Overview

OpenClaw is the assistant runtime and orchestration layer.

It provides:

• the main assistant session
• additional helper agents such as ops, heartbeat, hooks, and maintenance
• scheduled jobs
• routing and session handling
• tool execution
• access to surrounding nodes and environments

OpenClaw is where action happens.

That includes:

• answering questions
• running diagnostics
• scheduling periodic checks
• coordinating maintenance
• interacting with files, repos, and services

But action is not the same thing as truth.

If the assistant runtime also became the canonical place where the system's durable meaning lived, then every behavioral change, tool quirk, or runtime inconsistency would threaten the integrity of long-term structure.

That is why OpenClaw is treated as the execution layer rather than the sole source of durable truth.

This separation makes several things possible:

• the assistant can change behavior without redefining the system model every time
• multiple agents can operate within one shared operating model
• scheduled automation can be useful without becoming the owner of the underlying knowledge
• the control plane can remain stable even when runtime details are still evolving

In short: OpenClaw runs the system, but it does not get to silently redefine it.

The Org layer is the canonical internal operating system.

It holds:

• the system contract
• current status and integrity notes
• decisions and rationale
• infrastructure notes
• project records
• maintenance and publishing policy
• other meaning-bearing operational documents

The control plane is where meaning lives.

That means it should hold things like:

• what the system is supposed to do
• what the current state actually is
• what decisions have already been made
• what models are canonical
• what workflows are intended going forward

The control plane should not be the same thing as a generic docs bucket. It is a special-purpose root that exists specifically to hold the authoritative internal understanding of the system.

This avoids several common failures:

• operational decisions getting buried in random markdown files
• project structure being inferred from ad hoc notes
• runtime memory becoming the only place context exists
• canonical rules being spread implicitly across too many unrelated files

Org acts as the place where internal truth is made explicit enough to survive session loss, partial recovery, and tool churn.

The workspace is the payload layer that holds the actual files being managed.

The current top-level model is:

• `org/` = control plane
• `projects/`, `docs/`, `media/`, `data/`, `ops/`, `bin/` = payload roots
• `scratch/`, `archive/` = lifecycle roots

A control plane cannot replace the files themselves.

The system needs a place for:

• source code
• CAD files
• reference documents
• media libraries
• binaries
• structured datasets
• operational artifacts

Those things should live in real, usable filesystem locations rather than being forced into the note system just because the note system is well structured.

The workspace model exists to keep these categories from bleeding into one another.

For example:

• `org/` should hold an authoritative project record, not the CAD export itself
• `projects/` should hold active project payload, not every note about the project's meaning
• `docs/` should hold passive reference material, not become a hidden control plane
• `archive/` should preserve old material without pretending it is still live canonical state

This makes file placement easier to reason about because the workspace is organized by role, not by every possible format, vendor, or source.

Projects use one canonical file per project.

Each project file is structured with these top-level sections:

• Overview
• Tasks
• Spec
• Notes
• Decisions
• References

The system originally risked drifting into a more fragmented model where:

• one ledger tracked projects
• another tracked tasks
• another tracked requirements
• and per-project files held overlapping detail

That would have created multiple competing places to look for the same project.

Instead, the project file itself became canonical. That means the project has one obvious home, and the internal structure of that file carries the rest of the project's shape.

Each section solves a different problem:

• `Overview` identifies the project and its current state
• `Tasks` tracks the actual work to do
• `Spec` captures the intended end state, constraints, or design shape
• `Notes` allows looser working thought without forcing false structure
• `Decisions` records durable choices with rationale
• `References` holds supporting material

The point is not formalism for its own sake. The point is to keep the project readable to a human while still structured enough to maintain reliably.

Without a strong project model, the system would drift into:

• some work tracked in tasks
• some buried in prose
• some implied in old imports
• some only remembered conversationally

The one-file-per-project model reduces that ambiguity.

The publish model keeps internal truth separate from public-facing explanation.

The current model is:

1. internal canonical documents remain in Org
2. curated public-facing documents are created under `org/publish/`
3. the site repo consumes those curated docs
4. Hugo renders the public site

There is also a governance document at:

• `org/publish.org`

And a content layer split between:

• `org/publish/docs/` for non-project public docs
• `org/publish/projects/` for project-specific public docs

Internal records are designed for operating the system. They contain things like:

• active tasks
• rough notes
• operational decisions
• partial reconstruction details
• private or internal-only context

That is not the same thing as a clean public explanation.

If internal docs were published raw, the public layer would either become noisy and unsafe, or the internal layer would become artificially sanitized and lose its usefulness.

The publish layer solves that by introducing an intentional boundary.

The site repo is treated as:

• rendering layer
• deployment layer
• presentation layer

It is not supposed to be the first place public docs are shaped, because doing so would make the public website the accidental source of truth for documentation that should really be governed upstream.

The publish layer keeps the site downstream from the content model.

The current public site lives in the workspace under:

• `projects/code/www`

It is a Hugo site that deploys via GitHub Pages to:

• `https://danhill.us/`

A website has a different job than a control plane or a publish layer.

A website should:

• render content
• present information clearly
• be deployment-oriented
• stay focused on public consumption

It should not be the place where internal policy is negotiated or where operational records are stored.

Separating the site layer means:

• site redesign does not redefine internal truth
• public docs can be improved without changing underlying internal records
• deployment mechanics stay downstream from documentation intent

That is much healthier than letting a theme, generator, or website directory become the hidden center of the whole system.

A dedicated maintenance agent helps detect drift and perform small safe hygiene work.

The current implementation includes:

• a first-class maintenance agent
• a maintenance policy
• a cadence file
• a recurring cron job that invokes the maintenance agent

Systems drift even when their design is good.

Over time, things like these happen:

• duplicate journal fragments appear
• stale references accumulate
• backup files leak into canonical surfaces
• path assumptions lag reality
• publish flow gets bypassed
• project structure regresses quietly

Maintenance exists to catch that before the system requires another full archaeology dig.

The maintenance agent is not meant to become a roaming bureaucrat. It is allowed to:

• detect drift
• perform small reversible fixes
• archive clutter instead of deleting it
• raise issues that require review

It is not meant to:

• silently restructure the system
• redefine taxonomy
• merge or split semantic content on its own when evidence is ambiguous
• publish material automatically just because it looks plausible

That balance matters. A maintenance loop is valuable only if it reduces drift without becoming another source of it.