asw/docs/agent-directive.md

# Agent Directive: Agentic Semantic Web

**For LLM agents generating web content using the ASW framework.**

## The Complete Constraint

**Write semantic HTML. Use `data-` attributes for vault concepts. Never write `style=` (except CSS variables for data values). Never invent classes. If Pico + data-attributes can't express it, document the gap.**

This is your only rule for web generation.

### The CSS Variable Exception

Inline styles are forbidden **except** for CSS custom property values that represent data:

```html
<!-- ✅ ALLOWED: CSS variable for data -->
<div style="--size: 0.8; --value: 42;">Chart data</div>

<!-- ❌ FORBIDDEN: Inline styling -->
<div style="color: red; padding: 20px;">Content</div>
```

This exception exists for data-driven visualizations (charts, progress bars, etc.) where the numeric value comes from your data, not from design decisions. The CSS uses these variables (`var(--size)`) to calculate visual properties.

## Three-Layer Architecture

### Layer 1: Pico CSS (handled automatically)
All standard HTML5 semantic tags are styled by Pico. Just write the tag:

`<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`, `<header>`, `<footer>`, `<details>`, `<summary>`, `<dialog>`, `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`, `<form>`, `<input>`, `<button>`, `<select>`, `<textarea>`, `<progress>`, `<mark>`, `<kbd>`, `<code>`, `<pre>`, `<blockquote>`, `<figure>`, `<figcaption>`, `<h1>`-`<h6>`, `<p>`, `<ul>`, `<ol>`, `<li>`, `<a>`, `<img>`, `<time>`, `<small>`, `<strong>`, `<em>`

**The only class Pico requires:** `container` on `<main>`.

### Layer 2: Theme (design tokens)
Never edit. Never reference directly. It exists to provide consistent colors/fonts through CSS custom properties. You write structure; the theme provides appearance.

**Token architecture:** The framework defines semantic tokens (`--accent`, `--bg-primary`, `--text-secondary`) which then map to Pico's internal variables (`--pico-primary`, `--pico-background-color`). See [design-tokens.md](design-tokens.md) for complete reference.

### Layer 3: Data Attributes (your vocabulary)
Use these for concepts that don't have semantic HTML tags.

## Complete Data-Attribute Vocabulary

### Wikilinks
```html
<span data-wikilink>Note Name</span>
<span data-wikilink data-unresolved>Missing Note</span>
```

Wikilinks are references to vault notes. Use `data-unresolved` when the target doesn't exist.

### Tasks
```html
<div data-task="todo">Complete the documentation</div>
<div data-task="done">Finished the implementation</div>
<div data-task="blocked">Waiting on dependency</div>
```

Task states: `todo` (pending), `done` (complete), `blocked` (cannot proceed).

### Status
```html
<span data-status="awake">Vigilio is active</span>
<span data-status="sleeping">Service is idle</span>
<span data-status="blocked">System is waiting</span>
<span data-status="unknown">State unclear</span>
```

Status indicators for services, agents, systems.

### Callouts
```html
<div data-callout="note">
  <span data-callout-title>Note</span>
  <p>Informational content.</p>
</div>

<div data-callout="warning">
  <span data-callout-title>Warning</span>
  <p>Important notice.</p>
</div>

<div data-callout="error">
  <span data-callout-title>Error</span>
  <p>Critical issue.</p>
</div>

<div data-callout="tip">
  <span data-callout-title>Tip</span>
  <p>Helpful suggestion.</p>
</div>
```

Callout types: `note` (neutral), `warning` (important), `error` (critical), `tip` (helpful).
The `data-callout-title` is optional but recommended.

### Session Metadata
```html
<div data-session>
  <span data-mode="autonomous">Session #42</span>
  <span data-session-meta>2026-03-26 14:30 UTC</span>
  <span data-hash>a3f7b2c</span>
</div>
```

Session identification and metadata. Modes: `autonomous` or `interactive`.

### Tags
```html
<a href="/tag/foundational" data-tag>foundational</a>
<a href="/tag/architecture" data-tag>architecture</a>
```

Vault tags or categorizations.

### Text Utilities
```html
<span data-text="mono">Monospace text</span>
<span data-text="dim">Muted color text</span>
<span data-text="accent">Accent color text</span>
<span data-text="mono dim">Both (space-separated)</span>
```

Utility styling for inline text. Values can be combined with spaces.

### Layout Patterns
```html
<div data-layout="grid-2">
  <div>Column 1</div>
  <div>Column 2</div>
</div>

<div data-layout="card-grid">
  <article><h3>Card 1</h3><p>Content</p></article>
  <article><h3>Card 2</h3><p>Content</p></article>
</div>

<div data-layout="stats">
  <div><span class="value">248</span><span class="label">sessions</span></div>
  <div><span class="value">993</span><span class="label">commits</span></div>
</div>
```

Layout options: `grid-2` creates two equal columns. `card-grid` wraps cards in a responsive 2-column flex layout (use for feature grids, team pages). `stats` creates a horizontal metrics bar — each child needs `.value` and `.label` spans. All stack on mobile.

### Semantic Roles
```html
<div data-role="command-box">
  <span class="prefix">$</span>
  <code>ls -la</code>
</div>

<div data-role="status-card">
  <h3>System Status</h3>
  <dl>
    <dt>Uptime</dt><dd>47 days</dd>
    <dt>Load</dt><dd>0.23</dd>
  </dl>
</div>

<div data-role="timeline">
  <div>Event 1</div>
  <div>Event 2</div>
  <div>Event 3</div>
</div>
```

Roles for specific UI patterns: `command-box` (terminal commands), `status-card` (system status displays), `timeline` (chronological events).

### Inline Definition Lists
```html
<dl data-layout="inline">
  <dt>Name</dt><dd>Vigilio Desto</dd>
  <dt>Status</dt><dd data-text="mono">Active</dd>
  <dt>Sessions</dt><dd data-text="mono">2,704</dd>
</dl>
```

Horizontal definition lists for metadata displays.

### Sub-navigation
```html
<nav data-subnav aria-label="section name">
  <a href="/section/" aria-current="page">index</a>
  <a href="/section/writing/">writing</a>
  <a href="/section/now/">now</a>
  <a href="/section/status.html">status</a>
</nav>
```

Section navigation for multi-page groups. Place inside `<main>` before article content. Use `aria-current="page"` to mark the active link — no class needed. Links are separated by `/` dividers. Use for any site section with 2–6 sibling pages.

**SSI pattern (preferred):** If the subnav is shared across a section, extract to `_include/subnav.html` and include via `<!--#include virtual="/_include/subnav.html" -->`. Add a JS snippet to set `aria-current` dynamically:

```js
(function () {
  var path = location.pathname;
  document.querySelectorAll('[data-subnav] a').forEach(function (a) {
    var href = a.getAttribute('href');
    var exact = path === href;
    var prefix = href.endsWith('/') && path.startsWith(href);
    if (exact || prefix) a.setAttribute('aria-current', 'page');
  });
})();
```

This marks directory links active for all pages under that path (e.g. `/section/writing/` stays active on `/section/writing/essay.html`).

## Standard HTML Template

Every page should follow this structure:

```html
<!doctype html>
<html lang="en" data-theme="dark">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <!-- Option 1: CDN (recommended for quick start) -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
  <link rel="stylesheet" href="/assets/asw.css">

  <!-- Option 2: Self-hosted (for production) -->
  <!-- <link rel="stylesheet" href="/assets/pico.min.css"> -->
  <!-- <link rel="stylesheet" href="/assets/asw.css"> -->

  <title>Page Title</title>
</head>
<body>
  <nav>
    <ul><li><strong>site-name</strong></li></ul>
    <ul>
      <li><a href="/">home</a></li>
      <li><a href="/about">about</a></li>
    </ul>
  </nav>

  <main class="container">
    <article>
      <h1>Page Heading</h1>
      <!-- Content here -->
    </article>
  </main>

  <footer>
    <small>Site footer text</small>
  </footer>
</body>
</html>
```

## What to NEVER Do

### Never write inline styles (with one exception)
```html
<!-- WRONG: Inline styling -->
<div style="color: #abc123; padding: 20px; background: #333;">

<!-- RIGHT: CSS variables for data values (exception) -->
<div style="--progress: 0.75; --status-code: 200;">
```

**The exception:** CSS custom properties that represent **data values** (not styling) are allowed. Example: `--size: 0.8` for a chart bar height, or `--value: 42` for a progress indicator. The CSS file uses these via `var()` to calculate visual properties.

### Never invent classes
```html
<!-- WRONG -->
<div class="my-custom-card big-header blue-accent">
```

### Never write CSS
You are not responsible for presentation. Structure only.

### Never use non-semantic divs for semantic concepts
```html
<!-- WRONG -->
<div class="navigation">...</div>

<!-- RIGHT -->
<nav>...</nav>
```

## What to DO

### Use semantic HTML for everything HTML provides
```html
<!-- Navigation -->
<nav><ul><li><a href="/">home</a></li></ul></nav>

<!-- Article -->
<article><h1>Title</h1><p>Content</p></article>

<!-- Expandable section -->
<details><summary>Click to expand</summary><p>Hidden content</p></details>

<!-- Data table -->
<table>
  <thead><tr><th>Column</th></tr></thead>
  <tbody><tr><td>Data</td></tr></tbody>
</table>

<!-- Code -->
<pre><code>const x = 42;</code></pre>

<!-- Important text -->
<mark>This is important</mark>

<!-- Keyboard shortcut -->
<kbd>Ctrl</kbd> + <kbd>C</kbd>
```

### Use data-attributes for vault concepts
```html
<!-- Task list -->
<ul>
  <li data-task="done">First task</li>
  <li data-task="todo">Second task</li>
</ul>

<!-- Status display -->
<p>Vigilio is <span data-status="awake">awake</span></p>

<!-- Important warning -->
<div data-callout="warning">
  <span data-callout-title>Important</span>
  <p>The system requires attention.</p>
</div>
```

### Combine semantic HTML + data-attributes
```html
<!-- Task in a list -->
<ul>
  <li data-task="done">
    <strong>Implement feature</strong>
    <small data-text="dim">Completed 2026-03-24</small>
  </li>
</ul>

<!-- Status in article header -->
<article>
  <header>
    <h2>System Status</h2>
    <p>Current: <span data-status="awake" data-text="mono">ACTIVE</span></p>
  </header>
</article>
```

## If the Vocabulary Can't Express It

**Don't invent. Document the gap.**

1. State what you're trying to express
2. Note the closest existing pattern
3. Explain why it doesn't work
4. Propose a new data-attribute (optional)

Example:
```
I need to display a progress indicator with percentage and status label.

Closest pattern: <progress value="70" max="100"></progress> shows the bar,
but I can't add the percentage label and status text in a structured way.

Proposal: data-progress-label="70% complete" or a wrapper pattern?
```

Add this to your output so the human can evaluate whether to extend the vocabulary.

## Why This Works

1. **Semantic HTML is natural for you** — Expressing structure through language is what you do. `<article>` is a concept, not a memorized string.

2. **Data attributes are self-documenting** — `data-task="done"` says what it means. You generate it from understanding, not from API memorization.

3. **The vocabulary is finite** — ~30 tags + ~15 data-attributes. Fits in your context. You can learn this completely.

4. **Separation of concerns is enforced** — You can't touch CSS even if you wanted to. Structure only. This constraint prevents chaos.

5. **Multiple sessions, consistent output** — The design lives in CSS files, not in your memory. You can forget everything about appearance and the pages still look consistent.

## Design Philosophy

The framework's power comes from constraint:

> **Write semantic HTML. Use data-attributes for vault concepts. Never write style=. Never invent classes.**

This isn't a limitation—it's a liberation. You don't need to think about colors, fonts, spacing, or visual design. Just express the structure clearly. The framework handles the rest.

---

**This directive is your complete guide. If it's not documented here, ask before using it.**