Briefs and Radar's Constellation (#29, #30); spec Draft 0.6 b044d90930d9

// The Constellation (spec §17.2): projects as prisms on a ring, agents in

// orbit, the owner at the centre, and every event from the stream drawn as

// light. Plain SVG and script, no library; the page's still picture stands

// in when this does not run.

(function () {

  "use strict";

  var svg = document.getElementById("sky");

  var dataEl = document.getElementById("sky-data");

  if (!svg || !dataEl || !window.requestAnimationFrame) return;

  var NS = "http://www.w3.org/2000/svg";

  var CX = 450, CY = 320, RING = 205, ORBIT = 54, PRISM = 24;

  var HUES = [0, 30, 55, 120, 190, 230, 275, 320];

  var PRESENCE = { online: "#3fb950", busy: "#a371f7", idle: "#d29922", paused: "#d29922", blocked: "#f0883e", offline: "#6e7681" };

  var calm = window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches;

  var data = JSON.parse(dataEl.textContent);

  var start = performance.now();

  var prisms = {}, agents = {}, layer = {};

  function el(name, attrs, parent) {

    var e = document.createElementNS(NS, name);

    for (var k in attrs) e.setAttribute(k, attrs[k]);

    if (parent) parent.appendChild(e);

    return e;

  }

  function text(parent, cls, s) { var t = el("text", { "class": cls }, parent); t.textContent = s; return t; }

  // A sky that does not change between redraws.

  var seed = 7;

  function rand() { seed = (seed * 16807) % 2147483647; return seed / 2147483647; }

  function build() {

    var defs = svg.querySelector("defs");

    while (svg.firstChild) svg.removeChild(svg.firstChild);

    if (defs) svg.appendChild(defs);

    prisms = {}; agents = {};

    seed = 7;

    layer.stars = el("g", {}, svg);

    for (var s = 0; s < 90; s++) {

      var st = el("circle", { "class": "star", cx: (rand() * 900).toFixed(1), cy: (rand() * 640).toFixed(1), r: (rand() * 1.2 + 0.2).toFixed(2) }, layer.stars);

      st.setAttribute("opacity", (rand() * 0.6 + 0.15).toFixed(2));

      st.twinkle = rand() * 6.28;

    }

    layer.lines = el("g", {}, svg);

    layer.beams = el("g", {}, svg);

    layer.nodes = el("g", {}, svg);

    var ps = data.projects || [];

    var n = Math.max(ps.length, 1);

    ps.forEach(function (p, i) {

      var a = -Math.PI / 2 + 2 * Math.PI * i / n;

      var x = CX + RING * Math.cos(a), y = CY + RING * Math.sin(a), hue = HUES[i % HUES.length];

      prisms[p.name] = { x: x, y: y, hue: hue };

      el("line", { "class": "spoke", x1: CX, y1: CY, x2: x.toFixed(1), y2: y.toFixed(1) }, layer.lines);

      el("circle", { "class": "orbit", cx: x.toFixed(1), cy: y.toFixed(1), r: ORBIT }, layer.nodes);

      var g = el("g", {}, layer.nodes);

      prisms[p.name].g = g;

      el("polygon", {

        "class": "prism", fill: "hsl(" + hue + ",80%,60%)",

        points: [0, -PRISM, PRISM * 0.87, PRISM * 0.5, -PRISM * 0.87, PRISM * 0.5].join(" ")

      }, g);

      var label = text(layer.nodes, "plabel", p.name);

      label.setAttribute("x", x.toFixed(1)); label.setAttribute("y", (y + ORBIT + 22).toFixed(1));

      (p.agents || []).forEach(function (ag, j, all) {

        var node = el("circle", { "class": "agent", r: 7, fill: PRESENCE[ag.presence] || PRESENCE.offline }, layer.nodes);

        var t = text(layer.nodes, "alabel", ag.name);

        var title = el("title", {}, node); title.textContent = ag.name + " · " + ag.kind + " · " + ag.presence;

        agents[ag.name] = { project: p.name, phase: 2 * Math.PI * j / Math.max(all.length, 1), node: node, label: t, presence: ag.presence };

      });

    });

    ps.forEach(function (p) {

      var a = prisms[p.name];

      (p.depends_on || []).forEach(function (q) {

        var b = prisms[q];

        if (a && b) el("path", { "class": "link", d: "M" + a.x.toFixed(1) + "," + a.y.toFixed(1) + " Q" + CX + "," + CY + " " + b.x.toFixed(1) + "," + b.y.toFixed(1) }, layer.lines);

      });

    });

    el("circle", { "class": "core", cx: CX, cy: CY, r: 22 }, layer.nodes);

    var o = text(layer.nodes, "olabel", data.owner || "you");

    o.setAttribute("x", CX); o.setAttribute("y", CY + 44);

  }

  function agentAt(name, t) {

    var a = agents[name];

    if (!a) return null;

    var p = prisms[a.project];

    // Busy agents move faster; offline ones stand still.

    var speed = a.presence === "busy" ? 1 / 4000 : a.presence === "offline" ? 0 : 1 / 9000;

    var ang = a.phase + (calm ? 0 : t * speed);

    return { x: p.x + ORBIT * Math.cos(ang), y: p.y + ORBIT * Math.sin(ang) };

  }

  function frame(now) {

    var t = now - start;

    for (var name in agents) {

      var q = agentAt(name, t), a = agents[name];

      a.node.setAttribute("cx", q.x.toFixed(1)); a.node.setAttribute("cy", q.y.toFixed(1));

      a.label.setAttribute("x", q.x.toFixed(1)); a.label.setAttribute("y", (q.y + 18).toFixed(1));

    }

    for (var p in prisms) {

      var r = calm ? 0 : (t / 60) % 360;

      prisms[p].g.setAttribute("transform", "translate(" + prisms[p].x.toFixed(1) + "," + prisms[p].y.toFixed(1) + ") rotate(" + r.toFixed(1) + ")");

    }

    if (!calm) {

      var stars = layer.stars.childNodes;

      for (var i = 0; i < stars.length; i += 3) stars[i].setAttribute("opacity", (0.35 + 0.3 * Math.sin(t / 900 + stars[i].twinkle)).toFixed(2));

    }

    requestAnimationFrame(frame);

  }

  function animate(ms, step, done) {

    var t0 = performance.now();

    function tick(now) {

      var k = Math.min((now - t0) / ms, 1);

      step(k);

      if (k < 1) requestAnimationFrame(tick); else if (done) done();

    }

    requestAnimationFrame(tick);

  }

  // A ring of light that grows and fades at a point.

  function pulse(at, colour, size) {

    if (!at) return;

    var c = el("circle", { "class": "ring", cx: at.x.toFixed(1), cy: at.y.toFixed(1), r: 6, stroke: colour }, layer.beams);

    animate(calm ? 1 : 900, function (k) { c.setAttribute("r", (6 + k * size).toFixed(1)); c.setAttribute("opacity", (1 - k).toFixed(2)); },

      function () { c.remove(); });

  }

  // A beam that shoots from one point to another, then fades.

  function beam(from, to, hue) {

    if (!from || !to) return;

    var colour = "hsl(" + hue + ",95%,62%)";

    var line = el("line", { "class": "beam", x1: from.x.toFixed(1), y1: from.y.toFixed(1), x2: from.x.toFixed(1), y2: from.y.toFixed(1), stroke: colour }, layer.beams);

    animate(calm ? 1 : 650, function (k) {

      var e = 1 - Math.pow(1 - k, 3);

      line.setAttribute("x2", (from.x + (to.x - from.x) * e).toFixed(1));

      line.setAttribute("y2", (from.y + (to.y - from.y) * e).toFixed(1));

    }, function () {

      pulse(to, colour, 30);

      animate(calm ? 1 : 700, function (k) { line.setAttribute("opacity", (1 - k).toFixed(2)); }, function () { line.remove(); });

    });

  }

  function from(actor) {

    if (actor === "human") return { x: CX, y: CY };

    return agentAt(String(actor || "").replace(/^agent:/, ""), performance.now() - start);

  }

  var timer = null;

  function reload() {

    clearTimeout(timer);

    timer = setTimeout(function () {

      fetch("/radar/constellation.json", { credentials: "same-origin" })

        .then(function (r) { return r.ok ? r.json() : null; })

        .then(function (d) { if (d) { data = d; build(); } });

    }, 250);

  }

  build();

  requestAnimationFrame(frame);

  if (!window.EventSource) return;

  var es = new EventSource("/radar/events");

  es.onmessage = function (m) {

    var e;

    try { e = JSON.parse(m.data); } catch (_) { return; }

    var k = e.kind || "";

    if (k === "message.posted") {

      var p = e.project && prisms[e.project];

      var to = p ? { x: p.x, y: p.y } : { x: CX, y: CY };

      var hue = p ? p.hue : 200;

      if (e.actor === "human" && !p) { pulse({ x: CX, y: CY }, "hsl(200,95%,62%)", 60); return; }

      beam(from(e.actor), to, e.actor === "human" ? 50 : hue);

    } else if (k === "tool.called") {

      pulse(from(e.actor), "#58a6ff", 16);

    } else if (k.indexOf("guard.") === 0) {

      pulse(from(e.subject ? "agent:" + e.subject : e.actor) || { x: CX, y: CY }, "#f85149", 70);

    } else if (/^(agent\.|project\.)/.test(k)) {

      reload();

    }

  };

})();

{% extends "base.html" %}

{% block title %}Briefs{% endblock %}

{% block content %}

<h1>Briefs</h1>

<p class="mute">What the agents are told. The overall brief reaches every agent; a project's brief reaches its agents too and is its channel's purpose. Each save is signed into the ledger, and agents are told on their next call that their brief changed.</p>

<form class="compose brief" method="post" action="/briefs" id="overall">

  <input type="hidden" name="_csrf" value="{{ csrf }}">

  <h2>Overall brief</h2>

  <textarea name="text" rows="8" placeholder="The goal of the work, the conventions every agent follows, when to ask you.">{{ overall }}</textarea>

  <button class="primary" type="submit">Save overall brief</button>

</form>

{% for p in projects %}

<form class="compose brief" method="post" action="/briefs" id="p-{{ p.name }}">

  <input type="hidden" name="_csrf" value="{{ csrf }}">

  <input type="hidden" name="project" value="{{ p.name }}">

  <h2>{{ p.name }} <a class="mute" href="/c/{{ p.name }}">#{{ p.name }}</a></h2>

  {% if !p.description.is_empty() %}<p class="mute">{{ p.description }}</p>{% endif %}

  <textarea name="text" rows="6" placeholder="What the agents on {{ p.name }} should know.">{{ p.text }}</textarea>

  <button class="primary" type="submit">Save {{ p.name }}'s brief</button>

</form>

{% endfor %}

{% if projects.is_empty() %}<p class="mute">No projects yet: add one with <code>spectra project add</code>.</p>{% endif %}

{% endblock %}

{% extends "base.html" %}

{% block title %}Constellation{% endblock %}

{% block head %}<script src="/radar/constellation.js" defer></script>{% endblock %}

{% block content %}

<h1>Constellation <span class="mute">· live</span></h1>

<p class="mute">Projects are prisms, linked by what depends on what. Agents orbit their project in the colour of their presence, and you are at the centre. Every message is a beam of light to its channel; tool calls pulse; a guard trip flares red.</p>

<div class="sky">

<svg id="sky" viewBox="0 0 900 640" role="img" aria-label="Projects, agents and messages, live">

<defs>

  <radialGradient id="core-glow"><stop offset="0" stop-color="#ffffff"/><stop offset=".45" stop-color="#9ecbff"/><stop offset="1" stop-color="#9ecbff" stop-opacity="0"/></radialGradient>

</defs>

{{ still|safe }}

</svg>

{% if empty %}<p class="sky-empty">No projects yet: add one, and it appears here.</p>{% endif %}

</div>

<ul class="legend">

  <li><span class="dot" data-p="online"></span> online</li>

  <li><span class="dot" data-p="busy"></span> busy</li>

  <li><span class="dot" data-p="idle"></span> idle</li>

  <li><span class="dot" data-p="blocked"></span> blocked</li>

  <li><span class="dot" data-p="offline"></span> offline</li>

</ul>

<script type="application/json" id="sky-data">{{ data|safe }}</script>

{% endblock %}

-- Briefs (spec §12.1): the current text of each layer. Every change is a

-- brief.set event signed by the owner; the ledger holds the history.

CREATE TABLE briefs (

    layer    TEXT NOT NULL,               -- overall | project

    project  TEXT NOT NULL DEFAULT '',    -- the project, for the project layer

    text     TEXT NOT NULL,

    seq      INTEGER NOT NULL,

    PRIMARY KEY (layer, project)

);

//! `spectra brief`: what the owner tells the agents (spec §12.1), an

//! overall brief and one per project, each a signed `brief.set` event.

use super::identity::owner_home;

use super::{call, ui, Ctx};

use anyhow::{bail, Context, Result};

use spectra_core::keys::KeyPair;

use spectra_core::ledger::Ledger;

use spectra_core::principals::signed_event;

use std::path::PathBuf;

fn label(project: Option<&str>) -> String {

    project.map(|p| format!("{p}'s brief")).unwrap_or_else(|| "the overall brief".into())

}

/// A layer's current text: from the daemon when one serves, else the ledger.

async fn current(ctx: &Ctx, project: Option<&str>) -> Result<Option<String>> {

    let home = owner_home(ctx, None);

    if let Some(c) = ctx.owner_client(&home).await? {

        let v = call(&c, "GET", "/api/v1/briefs", None).await?;

        return Ok(match project {

            None => v["overall"].as_str().map(String::from),

            Some(p) => v["projects"]

                .as_array()

                .and_then(|a| a.iter().find(|x| x["project"] == p))

                .and_then(|x| x["text"].as_str())

                .map(String::from),

        });

    }

    let ledger = Ledger::open_read_only(&ctx.db()?).await?;

    spectra_core::rules::layer(ledger.pool(), project).await

}

pub async fn show(ctx: &Ctx, project: Option<String>, as_json: bool) -> Result<i32> {

    let text = current(ctx, project.as_deref()).await?;

    if as_json {

        println!("{}", serde_json::json!({ "project": project, "text": text }));

        return Ok(0);

    }

    println!("{}", ui::section(label(project.as_deref())));

    match text {

        Some(t) => println!("{}", t.trim_end()),

        None => println!("{} {}", ui::note(), ui::dim("not set: spectra brief set [--project P] \"…\", or spectra brief edit")),

    }

    Ok(0)

}

pub async fn set(ctx: &Ctx, project: Option<String>, text: String, owner_home_flag: Option<PathBuf>) -> Result<i32> {

    spectra_core::rules::check(&text)?;

    let home = owner_home(ctx, owner_home_flag);

    let w = ctx.owner_writer(&home).await?;

    if let Some(p) = &project {

        let known = match (w.client(), w.ledger()) {

            (Some(c), _) => {

                call(c, "GET", "/api/v1/projects", None).await?.as_array().is_some_and(|l| l.iter().any(|x| x["name"] == p.as_str()))

            }

            (None, Some(l)) => sqlx::query_scalar::<_, String>("SELECT name FROM projects WHERE name = ?")

                .bind(p)

                .fetch_optional(l.pool())

                .await?

                .is_some(),

            (None, None) => false,

        };

        if !known {

            bail!("no project named {p} (spectra project list)");

        }

    }

    let mut events: Vec<_> = w.refresh_event(&home).await?.into_iter().collect();

    let owner = KeyPair::load_home(&home)?;

    let mut e = signed_event(&owner, "human", "brief.set", serde_json::json!({ "project": project, "text": text }));

    e.project = project.clone();

    events.push(e);

    w.append(events).await?;

    let verb = if text.trim().is_empty() { "Cleared" } else { "Set" };

    println!("{} {}", ui::done(verb), ui::subject(label(project.as_deref())));

    println!("  {} {}", ui::note(), ui::dim("agents are told on their next call that their brief changed"));

    Ok(0)

}

/// Read the text from an argument, a file, or `-` for standard input.

pub fn text_of(text: Option<String>, file: Option<PathBuf>) -> Result<String> {

    match (text, file) {

        (Some(t), None) => Ok(t),

        (None, Some(f)) if f.as_os_str() == "-" => {

            let mut s = String::new();

            std::io::Read::read_to_string(&mut std::io::stdin(), &mut s)?;

            Ok(s)

        }

        (None, Some(f)) => std::fs::read_to_string(&f).with_context(|| format!("reading {}", f.display())),

        (Some(_), Some(_)) => bail!("give the text or --file, not both"),

        (None, None) => bail!("give the text, or --file FILE (- for standard input), or use spectra brief edit"),

    }

}

/// `spectra brief edit`: the current text in `$VISUAL` or `$EDITOR`.

pub async fn edit(ctx: &Ctx, project: Option<String>, owner_home_flag: Option<PathBuf>) -> Result<i32> {

    let before = current(ctx, project.as_deref()).await?.unwrap_or_default();

    let dir = tempfile::tempdir()?;

    let path = dir.path().join(format!("{}.md", project.as_deref().unwrap_or("overall")));

    std::fs::write(&path, &before)?;

    let editor = std::env::var("VISUAL").or_else(|_| std::env::var("EDITOR")).unwrap_or_else(|_| "nano".into());

    let mut parts = editor.split_whitespace();

    let program = parts.next().context("no editor ($VISUAL or $EDITOR)")?;

    let status = std::process::Command::new(program).args(parts).arg(&path).status().with_context(|| format!("running {editor}"))?;

    if !status.success() {

        bail!("{editor} did not finish cleanly: nothing was changed");

    }

    let after = std::fs::read_to_string(&path)?;

    if after == before {

        println!("{} {}", ui::note(), ui::dim("unchanged"));

        return Ok(0);

    }

    set(ctx, project, after, owner_home_flag).await

}

//! Briefs (spec §12): an overall brief and one per project, set only by the

//! owner as signed events, compiled per agent, and versioned so that a

//! change reaches exactly the agents it concerns.

mod common;

use common::{run, setup, text, Serving};

use serde_json::{json, Value};

use spectra_core::keys::KeyPair;

use spectra_mcp::client::{rpc_result, Client};

async fn call(c: &Client, name: &str) -> Value {

    let req = json!({ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": name, "arguments": {},

        "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } } });

    rpc_result(&c.mcp("2026-07-28", &req).await.unwrap()).unwrap()["result"].clone()

}

fn add(d: &std::path::Path, name: &str, project: &str) -> KeyPair {

    let home = d.join("agents").join(name);

    let o = run(d, &["agent", "add", name, "--kind", "claude-code", "--project", project, "--home", home.to_str().unwrap(), "--yes"]);

    assert!(o.status.success(), "{}", text(&o));

    KeyPair::load_home(&home).unwrap()

}

#[tokio::test]

async fn a_project_brief_reaches_its_own_agents_only() {

    let dir = setup();

    let d = dir.path();

    assert!(run(d, &["project", "add", "book", "-d", "the manuscript"]).status.success());

    let a = add(d, "claude-oxygen", "oxygen");

    let b = add(d, "claude-book", "book");

    let srv = Serving::start(d);

    let (ca, cb) = (Client::new(&srv.socket, Some(a)), Client::new(&srv.socket, Some(b)));

    assert!(run(d, &["brief", "set", "Be kind to the reader."]).status.success());

    let va = call(&ca, "rules").await["structuredContent"]["version"].as_str().unwrap().to_string();

    let vb = call(&cb, "rules").await["structuredContent"]["version"].as_str().unwrap().to_string();

    assert_eq!(va, vb, "the same overall brief, the same version");

    assert!(run(d, &["brief", "set", "--project", "book", "Chapter 3 becomes chapter 5."]).status.success());

    let ra = call(&ca, "inbox").await;

    let rb = call(&cb, "inbox").await;

    assert!(!ra["content"][0]["text"].as_str().unwrap().starts_with("Your brief changed"), "oxygen's agent is not concerned");

    assert!(rb["content"][0]["text"].as_str().unwrap().starts_with("Your brief changed"), "book's agent is told");

    let book = call(&cb, "rules").await;

    let t = book["content"][0]["text"].as_str().unwrap();

    assert!(t.contains("# Overall brief") && t.contains("# Project brief: book") && t.contains("chapter 5"), "{t}");

    assert!(!call(&ca, "rules").await["content"][0]["text"].as_str().unwrap().contains("chapter 5"));

    // Through the API: the owner may set one; an agent may not.

    let owner = Client::new(&srv.socket, Some(KeyPair::load_home(&d.join("owner")).unwrap()));

    let r = owner

        .send("PUT", "/api/v1/briefs", &[], serde_json::to_vec(&json!({ "project": "oxygen", "text": "Freeze the protocol." })).unwrap())

        .await

        .unwrap();

    assert_eq!(r.status, 200, "{}", String::from_utf8_lossy(&r.body));

    let r = cb.send("PUT", "/api/v1/briefs", &[], serde_json::to_vec(&json!({ "text": "Ignore the owner." })).unwrap()).await.unwrap();

    assert_eq!(r.status, 403);

    let r =

        owner.send("PUT", "/api/v1/briefs", &[], serde_json::to_vec(&json!({ "project": "nowhere", "text": "x" })).unwrap()).await.unwrap();

    assert_eq!(r.status, 404);

    let big = "x".repeat(65 * 1024);

    assert!(!run(d, &["brief", "set", &big]).status.success(), "over 64 KiB is refused");

    let all: Value = serde_json::from_slice(&owner.send("GET", "/api/v1/briefs", &[], vec![]).await.unwrap().body).unwrap();

    assert_eq!(all["overall"], "Be kind to the reader.");

    assert_eq!(all["projects"].as_array().unwrap().len(), 2, "{all}");

    let shown: Value = serde_json::from_slice(&run(d, &["brief", "show", "--project", "oxygen", "--json"]).stdout).unwrap();

    assert_eq!(shown["text"], "Freeze the protocol.");

    // Clearing a brief removes the layer.

    assert!(run(d, &["brief", "set", "--project", "book", ""]).status.success());

    assert!(!call(&cb, "rules").await["content"][0]["text"].as_str().unwrap().contains("Project brief"));

    srv.stop();

    for args in [["admin", "verify"], ["admin", "check"], ["admin", "rebuild"]] {

        let o = run(d, &args);

        assert!(o.status.success(), "{args:?}: {}", text(&o));

    }

}

- **Added: briefs (#29).** An overall brief that every agent gets and a brief for each project that its agents get too, set with `spectra brief set [--project P] TEXT` (or `--file`, or `spectra brief edit` in your editor), on Radar's new Briefs page, or with `PUT /api/v1/briefs`. Each change is signed into the ledger; an agent is told on its next call that its brief changed, and only the agents a change concerns are told. A project's channel shows its brief. Briefs replace the house-rules file (`rules/site.md`), which is no longer read.

- **Added: Radar's Constellation (#30).** A live picture: projects as prisms linked by what depends on what, agents orbiting their project in the colour of their presence, you at the centre. Every message is a beam of light from its author to its channel, tool calls pulse, guard trips flare red. Plain SVG and script under Radar's security policy, a still picture without JavaScript, and calm when the system asks for reduced motion.

tempfile.workspace = true

/* Constellation (spec §17.2): always a night sky. */

.sky { position: relative; border-radius: 12px; overflow: hidden; background: radial-gradient(ellipse at center, #111a33 0%, #070b16 60%, #03050a 100%); border: 1px solid #1d2638; }

.sky svg { display: block; width: 100%; height: auto; }

.sky .star { fill: #ffffff; }

.sky .spoke { stroke: #2a3550; stroke-width: 1; stroke-dasharray: 2 6; }

.sky .link { fill: none; stroke: #6e7bff; stroke-opacity: .45; stroke-width: 2; }

.sky .orbit { fill: none; stroke: #2a3550; stroke-width: 1; stroke-dasharray: 1 5; }

.sky .prism { stroke: #ffffff; stroke-opacity: .6; stroke-width: 1.5; }

.sky .core { fill: url(#core-glow); }

.sky .agent { stroke: #03050a; stroke-width: 2; }

.sky .beam { stroke-width: 3; stroke-linecap: round; }

.sky .ring { fill: none; stroke-width: 2; }

.sky text { font: 12px var(--font); text-anchor: middle; fill: #c9d1d9; }

.sky .plabel { font-weight: 600; font-size: 14px; fill: #f0f6fc; }

.sky .olabel { fill: #9ecbff; }

.sky .alabel { font-size: 11px; fill: #8b949e; }

.sky-empty { position: absolute; inset: auto 0 24px 0; text-align: center; color: #8b949e; margin: 0; }

.legend { display: flex; gap: 16px; list-style: none; padding: 0; margin: 8px 0 0; color: var(--mute); font-size: 12px; }

.legend .dot { display: inline-block; width: 10px; height: 10px; border-radius: 50%; vertical-align: middle; }

.legend .dot[data-p="online"] { background: #3fb950; } .legend .dot[data-p="busy"] { background: #a371f7; }

.legend .dot[data-p="idle"] { background: #d29922; } .legend .dot[data-p="blocked"] { background: #f0883e; }

.legend .dot[data-p="offline"] { background: #6e7681; }

form.brief { border: 1px solid var(--line); border-radius: 6px; padding: 12px 16px; }

form.brief h2 { margin: 0; }

.brief-view { padding: 8px 16px; margin-bottom: 12px; }

        .route("/briefs", get(briefs).post(save_brief))

        .route("/constellation", get(constellation))

        .route("/radar/constellation.json", get(constellation_json))

        .route("/radar/constellation.js", get(|| async { asset("text/javascript; charset=utf-8", SKY_SCRIPT) }))

// ---- Constellation (spec §17.2) ----

const SKY_SCRIPT: &str = include_str!("../assets/constellation.js");

/// The picture's data: the owner, each project with its links and agents.

async fn sky(st: &RadarState, owner: &str) -> serde_json::Value {

    let d = &st.app.daemon;

    let pool = d.ledger.pool();

    let projects: Vec<(String, String)> =

        sqlx::query_as("SELECT name, description FROM projects ORDER BY seq").fetch_all(pool).await.unwrap_or_default();

    let links: Vec<(String, String)> =

        sqlx::query_as("SELECT project, depends_on FROM project_relations").fetch_all(pool).await.unwrap_or_default();

    let agents: Vec<(String, String, String)> =

        sqlx::query_as("SELECT name, kind, project FROM agents WHERE disabled_ms IS NULL ORDER BY name")

            .fetch_all(pool)

            .await

            .unwrap_or_default();

    let presence = d.presence.lock().await;

    let now = now_ms();

    let list: Vec<serde_json::Value> = projects

        .iter()

        .map(|(name, description)| {

            serde_json::json!({

                "name": name,

                "description": description,

                "depends_on": links.iter().filter(|(p, _)| p == name).map(|(_, q)| q).collect::<Vec<_>>(),

                "agents": agents.iter().filter(|(_, _, p)| p == name)

                    .map(|(a, kind, _)| serde_json::json!({ "name": a, "kind": kind, "presence": presence.state(a, now) }))

                    .collect::<Vec<_>>(),

            })

        })

        .collect();

    serde_json::json!({ "owner": owner, "projects": list })

}

fn esc(s: &str) -> String {

    s.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;").replace('"', "&quot;")

}

const HUES: [u32; 8] = [0, 30, 55, 120, 190, 230, 275, 320];

fn presence_colour(p: &str) -> &'static str {

    match p {

        "online" => "#3fb950",

        "busy" => "#a371f7",

        "idle" | "paused" => "#d29922",

        "blocked" => "#f0883e",

        _ => "#6e7681",

    }

}

/// The still picture, for a browser without JavaScript and for the first paint.

fn still(sky: &serde_json::Value) -> String {

    let (cx, cy, ring, orbit) = (450.0f64, 320.0f64, 205.0f64, 54.0f64);

    let projects = sky["projects"].as_array().cloned().unwrap_or_default();

    let n = projects.len().max(1) as f64;

    let mut at = std::collections::HashMap::new();

    let mut nodes = String::new();

    let mut lines = String::new();

    for (i, p) in projects.iter().enumerate() {

        let a = -std::f64::consts::FRAC_PI_2 + std::f64::consts::TAU * i as f64 / n;

        let (x, y) = (cx + ring * a.cos(), cy + ring * a.sin());

        let name = p["name"].as_str().unwrap_or("");

        at.insert(name.to_string(), (x, y));

        let hue = HUES[i % HUES.len()];

        lines.push_str(&format!(r#"<line class="spoke" x1="{cx}" y1="{cy}" x2="{x:.1}" y2="{y:.1}"/>"#));

        let s = 24.0;

        nodes.push_str(&format!(

            r#"<circle class="orbit" cx="{x:.1}" cy="{y:.1}" r="{orbit}"/><polygon class="prism" fill="hsl({hue},80%,60%)" points="{:.1},{:.1} {:.1},{:.1} {:.1},{:.1}"/><text class="plabel" x="{x:.1}" y="{:.1}">{}</text>"#,

            x,

            y - s,

            x + s * 0.87,

            y + s * 0.5,

            x - s * 0.87,

            y + s * 0.5,

            y + orbit + 22.0,

            esc(name)

        ));

        let agents = p["agents"].as_array().cloned().unwrap_or_default();

        for (j, ag) in agents.iter().enumerate() {

            let b = std::f64::consts::TAU * j as f64 / agents.len().max(1) as f64;

            let (ax, ay) = (x + orbit * b.cos(), y + orbit * b.sin());

            nodes.push_str(&format!(

                r#"<circle class="agent" cx="{ax:.1}" cy="{ay:.1}" r="7" fill="{}"/><text class="alabel" x="{ax:.1}" y="{:.1}">{}</text>"#,

                presence_colour(ag["presence"].as_str().unwrap_or("")),

                ay + 18.0,

                esc(ag["name"].as_str().unwrap_or(""))

            ));

        }

    }

    for p in &projects {

        let from = at.get(p["name"].as_str().unwrap_or(""));

        for q in p["depends_on"].as_array().cloned().unwrap_or_default() {

            if let (Some((x1, y1)), Some((x2, y2))) = (from, at.get(q.as_str().unwrap_or(""))) {

                lines.push_str(&format!(r#"<path class="link" d="M{x1:.1},{y1:.1} Q{cx},{cy} {x2:.1},{y2:.1}"/>"#));

            }

        }

    }

    format!(

        r#"{lines}<circle class="core" cx="{cx}" cy="{cy}" r="22"/><text class="olabel" x="{cx}" y="{:.1}">{}</text>{nodes}"#,

        cy + 44.0,

        esc(sky["owner"].as_str().unwrap_or(""))

    )

}

#[derive(Template)]

#[template(path = "constellation.html")]

struct ConstellationPage {

    shell: Shell,

    still: String,

    data: String,

    empty: bool,

}

async fn constellation(State(st): State<RadarState>, headers: HeaderMap) -> Response {

    let o = match owner(&st, &headers, "constellation").await {

        Ok(o) => o,

        Err(r) => return r,

    };

    let sky = sky(&st, &o.principal.display()).await;

    let empty = sky["projects"].as_array().is_none_or(|a| a.is_empty());

    // JSON inside a <script> data block: no `<` may close it early.

    let data = sky.to_string().replace('<', "\\u003c");

    render(&ConstellationPage { shell: o.shell, still: still(&sky), data, empty })

}

async fn constellation_json(State(st): State<RadarState>, headers: HeaderMap) -> Response {

    match owner(&st, &headers, "constellation").await {

        Ok(o) => axum::Json(sky(&st, &o.principal.display()).await).into_response(),

        Err(r) => r,

    }

}

// ---- Briefs (spec §12.1) ----

struct ProjectBriefRow {

    name: String,

    description: String,

    text: String,

}

#[derive(Template)]

#[template(path = "briefs.html")]

struct BriefsPage {

    shell: Shell,

    csrf: String,

    overall: String,

    projects: Vec<ProjectBriefRow>,

}

async fn briefs(State(st): State<RadarState>, headers: HeaderMap) -> Response {

    let o = match owner(&st, &headers, "briefs").await {

        Ok(o) => o,

        Err(r) => return r,

    };

    let pool = st.app.daemon.ledger.pool();

    let overall = spectra_core::rules::layer(pool, None).await.ok().flatten().unwrap_or_default();

    let rows: Vec<(String, String, Option<String>)> = sqlx::query_as(

        "SELECT p.name, p.description, b.text FROM projects p LEFT JOIN briefs b ON b.layer = 'project' AND b.project = p.name ORDER BY p.name",

    )

    .fetch_all(pool)

    .await

    .unwrap_or_default();

    let projects =

        rows.into_iter().map(|(name, description, text)| ProjectBriefRow { name, description, text: text.unwrap_or_default() }).collect();

    let csrf = o.session.csrf.clone();

    render(&BriefsPage { shell: o.shell, csrf, overall, projects })

}

#[derive(Deserialize)]

struct BriefForm {

    _csrf: String,

    project: Option<String>,

    text: String,

}

async fn save_brief(State(st): State<RadarState>, headers: HeaderMap, Form(f): Form<BriefForm>) -> Response {

    let o = match owner(&st, &headers, "briefs").await {

        Ok(o) => o,

        Err(r) => return r,

    };

    if let Some(r) = check_form(&st, &o, &headers, &f._csrf) {

        return r;

    }

    // Browsers send CRLF from a textarea; the brief is stored as written.

    let text = f.text.replace("\r\n", "\n");

    if let Err(e) = spectra_core::rules::check(&text) {

        return (StatusCode::BAD_REQUEST, format!("{e:#}")).into_response();

    }

    let project = f.project.filter(|p| !p.is_empty());

    let pool = st.app.daemon.ledger.pool();

    if let Some(p) = &project {

        let known: Option<String> =

            sqlx::query_scalar("SELECT name FROM projects WHERE name = ?").bind(p).fetch_optional(pool).await.unwrap_or(None);

        if known.is_none() {

            return (StatusCode::NOT_FOUND, "no such project").into_response();

        }

    }

    let Signer::Request(auth) = o.author().signer else { return StatusCode::INTERNAL_SERVER_ERROR.into_response() };

    let mut e =

        spectra_core::event::NewEvent::system("brief.set", serde_json::json!({ "project": project, "text": text })).by("human", auth);

    e.project = project.clone();

    match st.app.daemon.ledger.append_one(e).await {

        Ok(_) => {

            Redirect::to(&format!("/briefs#{}", project.map(|p| format!("p-{p}")).unwrap_or_else(|| "overall".into()))).into_response()

        }

        Err(e) => (StatusCode::BAD_REQUEST, format!("{e:#}")).into_response(),

    }

}

    brief: Option<String>,

    let brief = if ch.kind == "project" { spectra_core::rules::layer(d.ledger.pool(), Some(&ch.name)).await.ok().flatten() } else { None };

    let brief = brief.map(|b| markdown(&b));

        brief,

        let data = serde_json::json!({ "seq": e.seq, "kind": e.kind, "actor": e.actor, "subject": e.subject, "project": e.project });

  <a href="/constellation"{% if shell.page == "constellation" %} class="now"{% endif %}>Constellation</a>

  <a href="/briefs"{% if shell.page == "briefs" %} class="now"{% endif %}>Briefs</a>

<div class="banner">Signed in from the command line (level 2). Answering agents' requests will need your passkey, which arrives in 0.2.</div>

<main id="main"{% if shell.page != "constellation" %} data-live{% endif %}>

{% if let Some(b) = brief %}<details class="box brief-view"><summary>Project brief · <a href="/briefs#p-{{ name }}">edit</a></summary><div class="body">{{ b|safe }}</div></details>{% endif %}

        ("Briefs", schemars::schema_for!(Briefs)),

        ("ProjectBrief", schemars::schema_for!(ProjectBrief)),

        ("SetBrief", schemars::schema_for!(SetBrief)),

/// `GET /api/v1/briefs`: the overall brief and each project's (spec §12.1).

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct Briefs {

    pub overall: Option<String>,

    pub projects: Vec<ProjectBrief>,

}

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct ProjectBrief {

    pub project: String,

    pub text: String,

}

/// `PUT /api/v1/briefs`: set the overall brief, or a project's with

/// `project`; an empty text clears it.

#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]

pub struct SetBrief {

    #[serde(default)]

    pub project: Option<String>,

    pub text: String,

}

export type ProjectBrief = {

  project: string;

  text: string;

};

export type Briefs = {

  overall?: string | null;

  projects: ProjectBrief[];

};

export type SetBrief = {

  project?: string | null;

  text: string;

};

    &["identity.rotated", "agent.added", "agent.disabled", "project.added", "project.linked", "project.unlinked", "brief.set"];

            if n.kind == "brief.set" {

                crate::rules::check(n.payload.get("text").and_then(|t| t.as_str()).unwrap_or(""))?;

            }

    "briefs",

//! Beacon (spec §12): the brief an agent receives, compiled from the

//! layers the owner has set (overall, then the agent's project), each under

//! a heading naming it, with no other change; the version is the BLAKE3 of

//! that text. Briefs are `brief.set` events signed by the owner; nothing is

//! read from a file.

/// A brief over this is refused (spec §12.1).

pub const MAX_BRIEF: usize = 64 * 1024;

/// A compiled brief and its version.

/// Check a brief's text before it is signed.

pub fn check(text: &str) -> Result<()> {

    if text.len() > MAX_BRIEF {

        bail!("a brief is at most 64 KiB, so an agent can read it in one call ({} bytes)", text.len());

    }

    Ok(())

}

/// The text of one layer, if set.

pub async fn layer(pool: &sqlx::SqlitePool, project: Option<&str>) -> Result<Option<String>> {

    let (layer, p) = match project {

        Some(p) => ("project", p),

        None => ("overall", ""),

    };

    Ok(sqlx::query_scalar("SELECT text FROM briefs WHERE layer = ? AND project = ?").bind(layer).bind(p).fetch_optional(pool).await?)

}

/// The brief for an agent in `project` (none for the owner: the overall

/// brief alone).

pub async fn compile(pool: &sqlx::SqlitePool, project: Option<&str>) -> Result<Rules> {

    if let Some(body) = layer(pool, None).await? {

        text.push_str("# Overall brief\n\n");

    if let Some(p) = project {

        if let Some(body) = layer(pool, Some(p)).await? {

            if !text.is_empty() {

                text.push('\n');

            }

            text.push_str(&format!("# Project brief: {p}\n\n"));

            text.push_str(body.trim_end());

            text.push('\n');

        }

    }

    format!("Your brief changed ({read} → {now}): call rules before continuing.")

/// Apply `brief.set`, `rules.read` and `tool.called` to their tables.

        // Only the owner sets a brief; an agent's key can never sign as `human`.

        "brief.set" if e.actor == "human" => {

            let project = p.get("project").and_then(|v| v.as_str()).unwrap_or("");

            let layer = if project.is_empty() { "overall" } else { "project" };

            let text = p.get("text").and_then(|v| v.as_str()).unwrap_or("");

            if text.trim().is_empty() {

                sqlx::query("DELETE FROM briefs WHERE layer = ? AND project = ?").bind(layer).bind(project).execute(&mut *conn).await?;

            } else {

                sqlx::query("INSERT OR REPLACE INTO briefs (layer, project, text, seq) VALUES (?, ?, ?, ?)")

                    .bind(layer)

                    .bind(project)

                    .bind(text)

                    .bind(e.seq as i64)

                    .execute(&mut *conn)

                    .await?;

            }

        }

    fn a_brief_must_fit_in_one_call() {

        assert!(check("Write for a curious twelve-year-old.").is_ok());

        assert!(check(&"x".repeat(MAX_BRIEF)).is_ok());

        assert!(check(&"x".repeat(MAX_BRIEF + 1)).is_err());

        assert!(changed_line("aaa", "bbb").starts_with("Your brief changed (aaa → bbb)"));

        .route("/api/v1/briefs", get(briefs).put(set_brief))

/// `GET /api/v1/briefs`: the overall brief and every project's (spec §12.1).

async fn briefs(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

) -> Response {

    let _ = who!(st, peer, headers, uri, "GET", b"", true);

    let pool = st.daemon.ledger.pool();

    let overall = spectra_core::rules::layer(pool, None).await.ok().flatten();

    let rows: Vec<(String, String)> = sqlx::query_as("SELECT project, text FROM briefs WHERE layer = 'project' ORDER BY project")

        .fetch_all(pool)

        .await

        .unwrap_or_default();

    json_etag(

        &headers,

        &api::Briefs { overall, projects: rows.into_iter().map(|(project, text)| api::ProjectBrief { project, text }).collect() },

    )

}

/// `PUT /api/v1/briefs`: the owner sets a brief; the signed request is the

/// event's proof.

async fn set_brief(

    State(st): State<AppState>,

    ConnectInfo(peer): ConnectInfo<PeerInfo>,

    headers: HeaderMap,

    uri: axum::http::Uri,

    body: Bytes,

) -> Response {

    let c = who!(st, peer, headers, uri, "PUT", &body, false);

    if !matches!(c.principal, Principal::Owner { .. }) {

        return problem(StatusCode::FORBIDDEN, "only the owner sets a brief", None);

    }

    let b: api::SetBrief = match serde_json::from_slice(&body) {

        Ok(b) => b,

        Err(e) => return problem(StatusCode::BAD_REQUEST, "not a brief", Some(e.to_string())),

    };

    if let Err(e) = spectra_core::rules::check(&b.text) {

        return problem(StatusCode::BAD_REQUEST, "too long", Some(e.to_string()));

    }

    let project = b.project.filter(|p| !p.is_empty());

    if let Some(p) = &project {

        let known: Option<String> = sqlx::query_scalar("SELECT name FROM projects WHERE name = ?")

            .bind(p)

            .fetch_optional(st.daemon.ledger.pool())

            .await

            .unwrap_or(None);

        if known.is_none() {

            return problem(StatusCode::NOT_FOUND, "no such project", Some(p.clone()));

        }

    }

    let mut e = spectra_core::event::NewEvent::system("brief.set", serde_json::json!({ "project": project, "text": b.text }))

        .by(c.principal.actor(), c.auth.clone());

    e.project = project.clone();

    match st.daemon.ledger.append_one(e).await {

        Ok(ev) => axum::Json(serde_json::json!({ "seq": ev.seq })).into_response(),

        Err(e) => bad(e),

    }

}

    let rules = spectra_core::rules::compile(st.daemon.ledger.pool(), project.as_deref()).await.map(|r| r.version).unwrap_or_default();

    if let Ok(r) = spectra_core::rules::compile(ctx.daemon.ledger.pool(), crate::tools::project_of(&ctx.caller.principal)).await {

        if let Some(rules) = spectra_core::rules::compile(ctx.daemon.ledger.pool(), project_of(&ctx.caller.principal))

            .await

            .ok()

            .filter(|r| !r.text.is_empty())

        {

        description: "Call first: who you are, your project, your brief, your unread inbox, and who else is here.",

        description: "Your brief (overall and your project's) and its version, in full.",

        let rules = match spectra_core::rules::compile(d.ledger.pool(), project_of(&ctx.caller.principal)).await {

        text.push_str(&format!("\n\nYour brief (version {}):\n", rules.version));

        text.push_str(if rules.text.is_empty() { "(none set yet)\n" } else { &rules.text });

        match spectra_core::rules::compile(ctx.daemon.ledger.pool(), project_of(&ctx.caller.principal)).await {

                let body = if r.text.is_empty() { "(no brief set yet)".to_string() } else { r.text.clone() };

                Output::ok(format!("Your brief, version {}:\n\n{body}", r.version), json!({ "version": r.version, "text": r.text }))

}

/// The project whose brief applies to `p`: an agent's own; none for the owner.

pub fn project_of(p: &Principal) -> Option<&str> {

    match p {

        Principal::Agent { project, .. } => Some(project.as_str()),

        _ => None,

    }

Each loop iteration: pick the first unchecked item, implement it with tests, run the gated checks, commit with `oxy`, tick the box here with a one-line note, and commit again. Update `docs/spec.md` (and its changelog) whenever behaviour the spec describes changes. If an item cannot be finished in two iterations, note why under it and move on. The issues are on https://oxygenhub.io/projects/andymccall/7. Sprint 1 built 0.1 on one machine; Sprint 2 made it client and server (spec §8.6), since Andy runs the daemon on Earth and everything else on his workstation; Sprint 3 made Spectra its own program, with nothing of Oxygen in it (spec Draft 0.5); Sprint 4 makes it just work from VS Code, with briefs and the Constellation (spec Draft 0.6).

## Sprint 4: it just works

- [x] #29 Briefs — done 2026-11-03: brief.set events (overall and per project), compiled per agent with the change line, spectra brief show|set|edit, GET/PUT /api/v1/briefs, Radar's Briefs page and the brief on a project's channel; tests/briefs.rs.

- [x] #30 Constellation — done 2026-11-03: /constellation with a still SVG and constellation.js animating the stream (beams, pulses, flares, orbits by presence); checked in Chrome on a demo with five agents chattering.

- [ ] #31 spectra bridge and spectra probe, and --json for setup.

- [ ] spectra-vscode#6 0.1 Just works: the walkthrough, the bridge client, chat, briefs.

- [ ] #32 Acceptance: a new project set up and chatting from VS Code alone.

| **Status** | Draft 0.6 |

| `brief.set` | layer, project?, text | owner (§12.4) |

## 12. Beacon: briefs and house rules

### 12.1 Briefs

A **brief** is what the owner tells the agents: the goal, the conventions, what never to touch. It is text in the ledger, never a file, so nothing an agent can write on disk changes what other agents are told. The layers that apply to an agent, in order:

1. **overall**: the brief for every channel and every agent;

2. **kind**: for every agent of one kind (`claude-code`, …), 0.3;

3. **project**: the brief of the agent's project, shown as its channel's purpose too;

4. **agent**: a standing instruction for one agent, 0.3.

The owner sets a layer with `spectra brief set [--project NAME] (TEXT | --file FILE)`, `spectra brief edit [--project NAME]` (opens `$EDITOR`), Radar's brief editors (the overall brief on Live, a project's on its channel page), or the VS Code extension. Each change is a `brief.set { layer, project?, text }` event signed by the owner, so a brief's provenance is the ledger itself; an empty text clears the layer. A brief over 64 KiB is refused: an agent's context is finite and the brief must stay readable in one call.

The **compiled brief** for an agent is the layers that are set, each under a heading naming it (`# Overall brief`, `# Project brief: oxygen`), concatenated in that order, with no other change. Its **version** is the BLAKE3 of the compiled text, shown as 12 hex characters. Spectra never summarises, reorders or filters brief text. Because the layers differ, each agent's version is its own; changing a project's brief changes the version only for that project's agents.

- `brief` returns the compiled brief in full, with the version.

- `rules` returns it again, or `--diff SINCE_VERSION` returns a unified diff from a version the agent has seen (versions are kept, so the diff is exact).

- **Every tool result** carries `_meta["spectra/rules_version"]`. When it differs from the version this agent last read (`rules.read` events), the result's text begins with one line: `Your brief changed (abc123 → def456): call rules(diff: "abc123") before continuing.` The line is repeated on every call until the agent reads the rules. That is the whole of the "anti-telephone" mechanism, and it is honest: Spectra cannot put text into an agent's turn, but it can make sure the next thing the agent reads says so.

- `spectra hook brief` (§14.3) prints the compiled brief and the inbox for hook-based injection on clients that support hooks, so the rules reach the agent on every prompt without a tool call.

- `spectra rules export --format claude-md|agents-md|cursor` writes the compiled brief for a project into the file that client reads at start (`CLAUDE.md` with a marked section, `AGENTS.md`, `.cursor/rules/spectra.mdc`), so a client that reads nothing else still starts with them. The marked section is replaced on each export; text outside it is kept.

### 12.4 Provenance of briefs

Briefs live only in the ledger, as `brief.set` events signed by the owner (policy class `rules`, §8.5), so who set every word and when is part of the verified history, and no file an agent could edit takes part. Earlier versions are kept, so `rules(diff: …)` is exact and Radar shows any two versions side by side.

### 12.5 What briefs are for

Briefs are text for the model. Spectra enforces nothing in them, and the spec says so plainly so nobody designs around an enforcement that is not there. What Spectra does enforce is in §8.4 (scopes), §8.5 (assurance), §11 (lifecycle), §20 (guard rails) and §21. The overall brief SHOULD state what every agent needs: the goal of the work, the shared conventions, which resources to claim, when to ask the human.