diff --git a/checks/fixtures/twin-dashboard.md b/checks/fixtures/twin-dashboard.md
new file mode 100644
index 0000000..9b73318
--- /dev/null
+++ b/checks/fixtures/twin-dashboard.md
@@ -0,0 +1,32 @@
+# Dashboard title
+
+`.clayo/pages/dashboard.html` · written 2026-11-18 12:00
+
+What these numbers cover and the one thing they say.
+
+1,284 label (+8% vs last week) · 99.2% label · 340 ms label · 7 label
+
+**Trend title**, a line chart:
+
+| | This week | Last week |
+|---|---|---|
+| Mon | 12 | 10 |
+| Tue | 19 | 14 |
+| Wed | 14 | 13 |
+| Thu | 22 | 17 |
+| Fri | 25 | 19 |
+
+**Breakdown title**, a doughnut chart:
+
+| | Share |
+|---|---|
+| A | 55 |
+| B | 30 |
+| C | 15 |
+
+## Table title
+
+| Name | Status | Value | Change |
+|---|---|---|---|
+| First | ok | 812 | +4% |
+| Second | slow | 472 | -2% |
diff --git a/checks/fixtures/twin-report.md b/checks/fixtures/twin-report.md
new file mode 100644
index 0000000..a374841
--- /dev/null
+++ b/checks/fixtures/twin-report.md
@@ -0,0 +1,37 @@
+# Report title
+
+`.clayo/pages/report.html` · written 2026-11-18 12:00
+
+One or two sentences with the conclusion, including the key number.
+
+Scope or date · Status
+
+312 label · 98.7% label (+1.2 since last run) · 4 label
+
+## First finding
+
+What you found and why it matters, in two or three sentences.
+
+> **Watch out.** The one thing the reader must not miss.
+
+## Details
+
+| Item | Status | Count | Time |
+|---|---|---|---|
+| `auth/login` | failed | 4 | 1.8 s |
+| `api/users` | passed | 120 | 0.6 s |
+
+## Chart or diagram
+
+**Chart title**, a bar chart:
+
+| | Series |
+|---|---|
+| A | 4 |
+| B | 7 |
+| C | 2 |
+
+## Next steps
+
+1. **Do this first.** Why, in a few words.
+2. **Then this.** Why, in a few words.
diff --git a/checks/fixtures/twin-slides.md b/checks/fixtures/twin-slides.md
new file mode 100644
index 0000000..ae611c8
--- /dev/null
+++ b/checks/fixtures/twin-slides.md
@@ -0,0 +1,73 @@
+# Deck title
+
+`.clayo/pages/slides.html` · written 2026-11-18 12:00
+
+The one-line message of the whole deck.
+
+---
+
+## A part of the deck
+
+What this part shows, in one line.
+
+---
+
+## A heading that states the point
+
+- A short bullet, one line.
+- Another, with the **key term** in bold.
+- At most four.
+
+---
+
+**42%**
+
+What the number is, in one line.
+
+---
+
+## Text on the left
+
+Two or three sentences about what the chart shows.
+
+A bar chart:
+
+| | Series |
+|---|---|
+| A | 4 |
+| B | 7 |
+| C | 2 |
+
+---
+
+## Numbers side by side
+
+312 label · 98% label · 4 label
+
+---
+
+## Three things side by side
+
+### First
+
+One or two lines.
+
+### Second
+
+One or two lines.
+
+### Third
+
+One or two lines.
+
+---
+
+> A sentence worth a slide of its own.
+
+— Who said it
+
+---
+
+## The one thing to remember
+
+What happens next, in one line.
diff --git a/checks/pages.cs b/checks/pages.cs
index a33b7e7..17c965f 100644
--- a/checks/pages.cs
+++ b/checks/pages.cs
@@ -321,6 +321,59 @@ string Bundle(string body) => PageBundle.Make(
Check(" odd types in the file read as nothing", (new PageShares(Path.Combine(dir, "shares.json")).Login, new PageShares(Path.Combine(dir, "shares.json")).All().Count), ((string?)null, 0));
Check(" a broken entry is skipped", new PageShares(Path.Combine(dir, "shares.json")).All().Count, 0);
Check("filter: shared only", string.Join(",", PageIndex.Filter([fixture[0], fixture[1] with { Shared = true }], new(Shared: true)).Select(p => p.Title)), "alpha");
+
+ // The text twin (P9, D18): markdown made from the page, for other sessions to read.
+ var fixtures = Path.Combine(AppContext.BaseDirectory, "..", "..", "..", "..", "..", "checks", "fixtures");
+ if (!Directory.Exists(fixtures)) fixtures = Path.Combine(Environment.CurrentDirectory, "fixtures");
+ var made = new DateTime(2026, 11, 18, 12, 0, 0);
+ foreach (var name in new[] { "report", "dashboard", "slides" })
+ {
+ var html = File.ReadAllText(Path.Combine(AppContext.BaseDirectory, "Assets", "pages", "templates", name + ".html"));
+ var twin = PageTwin.Make(html, name + ".html", made);
+ Check($"twin: {name}.html matches its fixture", twin, File.ReadAllText(Path.Combine(fixtures, $"twin-{name}.md")).ReplaceLineEndings("\n"));
+ if (name == "report") Console.WriteLine($" report twin: {twin.Length} of {html.Length} bytes ({100.0 * twin.Length / html.Length:F0}%)");
+ }
+ string Twin(string body) => PageTwin.Make($"
T{body}", "t.html", made);
+ Check(" the title first, then the file and when", Twin("
T
"), "# T\n\n`.clayo/pages/t.html` · written 2026-11-18 12:00\n\n\n");
+ Check(" a chart gives a data table",
+ Twin("")
+ .Contains("**Fails**, a bar chart (n):\n\n| | a | b |\n|---|---|---|\n| auth | 4 | 1 |\n| api | 0 | |"), true);
+ Check(" a scatter, a row per point", Twin("")
+ .Contains("| | x | y |\n|---|---|---|\n| s | 1 | 2 |\n| s | 3 | 4 |"), true);
+ Check(" broken chart JSON is left out", Twin("
a
").EndsWith("\n\na\n"), true);
+ Check(" Mermaid as a mermaid block", Twin("
\nflowchart LR\n A --> B\n
").Contains("```mermaid\nflowchart LR\n A --> B\n```"), true);
+ var deckTwin = Twin("
One
Two
Three
");
+ Check(" a deck: one section per slide", deckTwin.EndsWith("## One\n\n---\n\n## Two\n\n---\n\n## Three\n"), true);
+ Check(" layout as short lines", Twin("
312passed
4failed
")
+ .Contains("\n312 passed · 4 failed\n"), true);
+ Check(" no script, style or image data", Twin("
a
").EndsWith("\n\na [image: logo]\n"), true);
+ Check("index.html's twin is not the list", Path.GetFileName(PageTwin.PathOf(@"C:\p\.clayo\pages\index.html")), "index.html.md");
+
+ // The twin and index.md follow the index.
+ var twinDir = Path.Combine(dir, "twin", ".clayo", "pages");
+ Directory.CreateDirectory(twinDir);
+ var one = Path.Combine(twinDir, "one.html");
+ var two = Path.Combine(twinDir, "two.html");
+ File.WriteAllText(one, "First
hello
");
+ File.WriteAllText(two, "Second");
+ var twins = new PageIndex(Path.Combine(dir, "twins.json"));
+ twins.Record([one, two], Path.Combine(dir, "twin"), "s1", "Claude");
+ var list = Path.Combine(twinDir, PageTwin.IndexFile);
+ Check("record: the twin is written beside the page", File.Exists(Path.Combine(twinDir, "one.md")) && File.ReadAllText(Path.Combine(twinDir, "one.md")).Contains("\nhello\n"), true);
+ Check(" index.md lists every page", (File.ReadAllText(list).Contains("- First: `one.md` (page `one.html`)"), File.ReadAllText(list).Contains("- Second: `two.md`")), (true, true));
+ File.WriteAllText(one, "First
changed
");
+ File.SetLastWriteTimeUtc(one, DateTime.UtcNow.AddMinutes(1));
+ twins.Record([one], Path.Combine(dir, "twin"), "s1", "Claude");
+ Check(" a change rewrites the twin", File.ReadAllText(Path.Combine(twinDir, "one.md")).Contains("\nchanged\n"), true);
+ twins.Scan([Path.Combine(dir, "twin")]);
+ Check(" the scan lists no twin as a page", twins.Recent(int.MaxValue).Count, 2);
+ twins.Remove([two]);
+ Check("remove: the twin goes too", File.Exists(Path.Combine(twinDir, "two.md")), false);
+ Check(" and index.md drops it", File.ReadAllText(list).Contains("Second"), false);
+ File.Delete(one);
+ twins.Recent(10);
+ Check("a page that drops out takes its twin", File.Exists(Path.Combine(twinDir, "one.md")), false);
+ Check(" none left: no index.md", File.Exists(list), false);
}
finally { Directory.Delete(dir, recursive: true); }
diff --git a/checks/prompt.cs b/checks/prompt.cs
index 4d7a6ae..d046533 100644
--- a/checks/prompt.cs
+++ b/checks/prompt.cs
@@ -128,10 +128,32 @@ void Same(string name, object? got, object? want)
Same("a line carried on with \\: not", PagePrompt.Rewrite("/page x\\"), null);
Same("with a page open, the prompt names it",
PagePrompt.Rewrite("/page make the title shorter", @"C:\proj\.clayo\pages\test-results.html"),
- Head + " (open: `.clayo/pages/test-results.html`): make the title shorter.");
-Same("Claude: the open page goes on the end of the line", PagePrompt.OpenNote(@"C:\proj\.clayo\pages\a.html"), " (open: `.clayo/pages/a.html`)");
+ Head + ": make the title shorter. (page open: .clayo/pages/test-results.md)");
+Same("the open page goes on the end of the line, by its twin", PagePrompt.OpenNote(@"C:\proj\.clayo\pages\a.html"), " (page open: .clayo/pages/a.md)");
Same(" none open: nothing", PagePrompt.OpenNote(null), "");
+// The open page's twin is named on the first prompt after it opens or changes (P9), not on every one.
+{
+ const string Open = @"C:\proj\.clayo\pages\a.html";
+ const string Note = " (page open: .clayo/pages/a.md)";
+ var t0 = new DateTime(2026, 11, 18, 9, 0, 0, DateTimeKind.Utc);
+ var note = new OpenPageNote();
+ Same("twin: no page open, nothing", note.For("hello", null, t0), "");
+ Same(" the first prompt gets it", note.For("summarise this", Open, t0), Note);
+ Same(" the next doesn't", note.For("and shorter", Open, t0), "");
+ Same(" a change to the page brings it back", note.For("again", Open, t0.AddSeconds(5)), Note);
+ Same(" a slash command never", new OpenPageNote().For("/model", Open, t0), "");
+ Same(" nor a shell line or an empty one", (new OpenPageNote().For("!ls", Open, t0), new OpenPageNote().For(" ", Open, t0)), ("", ""));
+ note.Forget();
+ Same(" opened again: named again", note.For("hi", Open, t0.AddSeconds(5)), Note);
+ var cmd = new OpenPageNote();
+ Same(" /page always, once", cmd.For("/page x", Open, t0) + cmd.For("/page y", Open, t0), Note + Note);
+ Same(" and the prompt after it doesn't repeat it", cmd.For("thanks", Open, t0), "");
+ Same("/page gets one suffix, not two",
+ PagePrompt.Rewrite("/page x", Open)!.Split("(page open:").Length - 1, 1);
+ Same("Claude's /page says what the suffix means", PagePrompt.ClaudeCommand.Contains("(page open: .md)") && PagePrompt.ClaudeCommand.Contains(".html"), true);
+}
+
// The line at the prompt, from the keys alone.
string? Typed(params string[] keys)
{
diff --git a/src/Clayo/Assets/pages/page-guide.md b/src/Clayo/Assets/pages/page-guide.md
index a080583..e70fb42 100644
--- a/src/Clayo/Assets/pages/page-guide.md
+++ b/src/Clayo/Assets/pages/page-guide.md
@@ -3,6 +3,10 @@
A page is one HTML file that Clayo shows beside the terminal: a report, a dashboard, a
diagram or a slide deck. The design is already done. You write content and data.
+To read an existing page, read its `.md` twin (Clayo writes it beside the page; all of them are
+listed in `.clayo/pages/index.md`). `(page open: .md)` at the end of a prompt names the
+page open in Clayo by its twin; a change to it goes in `.html`. Never write a twin.
+
## 1. The contract
- One file: `.clayo/pages/.html`. Name in kebab-case from the title
diff --git a/src/Clayo/Pages/PageIndex.cs b/src/Clayo/Pages/PageIndex.cs
index a347041..58164e5 100644
--- a/src/Clayo/Pages/PageIndex.cs
+++ b/src/Clayo/Pages/PageIndex.cs
@@ -51,18 +51,23 @@ public PageIndex(string? file = null)
/// The pages whose files are still there.
public int Count => _pages.Count(p => File.Exists(p.Path));
- /// Adds the pages a session wrote, or brings the ones already known up to date.
+ ///
+ /// Adds the pages a session wrote, or brings the ones already known up to date, with their
+ /// text twins (PageTwin).
+ ///
public void Record(IEnumerable paths, string project, string? sessionId, string agent)
{
- foreach (var path in paths.Where(File.Exists))
+ var written = paths.Where(File.Exists).ToList();
+ foreach (var path in written)
{
var now = File.GetLastWriteTimeUtc(path);
int at = _pages.FindIndex(p => Same(p.Path, path));
var entry = new PageEntry(path, TitleOf(path), project, sessionId, agent, at < 0 ? now : _pages[at].Created, now);
if (at < 0) _pages.Add(entry);
else _pages[at] = entry;
+ PageTwin.Update(path);
}
- Save();
+ Save(written);
}
///
@@ -71,28 +76,37 @@ public void Record(IEnumerable paths, string project, string? sessionId,
///
public void Scan(IEnumerable projects)
{
- int before = _pages.Count;
+ var found = new List();
foreach (var project in projects.Distinct(StringComparer.OrdinalIgnoreCase))
{
var folder = System.IO.Path.Combine(project, ".clayo", "pages");
if (!Directory.Exists(folder)) continue;
try
{
+ // Only the pages: their twins and index.md are .md.
foreach (var path in Directory.EnumerateFiles(folder, "*.html"))
if (!_pages.Any(p => Same(p.Path, path)))
+ {
_pages.Add(new PageEntry(path, TitleOf(path), project, null, "",
File.GetCreationTimeUtc(path), File.GetLastWriteTimeUtc(path)));
+ PageTwin.Update(path);
+ found.Add(path);
+ }
}
catch (Exception e) when (e is IOException or UnauthorizedAccessException) { }
}
- if (_pages.Count != before) Save();
+ if (found.Count > 0) Save(found);
}
- /// Takes these pages out of the index (their files are deleted by the caller).
+ /// Takes these pages and their twins out of the index (the pages are deleted by the caller).
public void Remove(IEnumerable paths)
{
var gone = paths.ToHashSet(StringComparer.OrdinalIgnoreCase);
- if (_pages.RemoveAll(p => gone.Contains(p.Path)) > 0) Save();
+ var removed = _pages.Where(p => gone.Contains(p.Path)).Select(p => p.Path).ToList();
+ if (removed.Count == 0) return;
+ _pages.RemoveAll(p => gone.Contains(p.Path));
+ removed.ForEach(PageTwin.Delete);
+ Save(removed);
}
///
@@ -101,10 +115,14 @@ public void Remove(IEnumerable paths)
///
public IReadOnlyList Recent(int max)
{
- int before = _pages.Count;
+ var gone = _pages.Where(p => !File.Exists(p.Path)).Select(p => p.Path).ToList();
_pages = [.. _pages.Where(p => File.Exists(p.Path)).Select(p => p with { Changed = File.GetLastWriteTimeUtc(p.Path) })];
var recent = _pages.OrderByDescending(p => p.Changed).Take(max).Select(p => p with { Title = TitleOf(p.Path), Deck = IsDeck(p.Path) }).ToList();
- if (_pages.Count != before) Save();
+ if (gone.Count > 0)
+ {
+ gone.ForEach(PageTwin.Delete);
+ Save(gone);
+ }
return recent;
}
@@ -158,8 +176,11 @@ public static string TitleOf(string path)
return System.IO.Path.GetFileNameWithoutExtension(path);
}
- private void Save()
+ // Writes pages.json, and index.md in the folders of the pages that changed (PageTwin).
+ private void Save(IEnumerable changed)
{
+ foreach (var folder in changed.Select(System.IO.Path.GetDirectoryName).OfType().Distinct(StringComparer.OrdinalIgnoreCase))
+ PageTwin.WriteIndex(folder, _pages.Where(p => Same(System.IO.Path.GetDirectoryName(p.Path) ?? "", folder)));
try
{
Directory.CreateDirectory(System.IO.Path.GetDirectoryName(_file)!);
diff --git a/src/Clayo/Pages/PagePrompt.cs b/src/Clayo/Pages/PagePrompt.cs
index a6572ae..708e422 100644
--- a/src/Clayo/Pages/PagePrompt.cs
+++ b/src/Clayo/Pages/PagePrompt.cs
@@ -32,12 +32,15 @@ public static bool IsCommand(string line) =>
if (!IsCommand(line)) return null;
var text = line[Command.Length..].Trim().TrimEnd('.');
if (text.Length == 0) text = "a page of what we just discussed";
- return $"Make a Clayo page as `.clayo/page-guide.md` says{OpenNote(openPage)}: {text}.";
+ return $"Make a Clayo page as `.clayo/page-guide.md` says: {text}.{OpenNote(openPage)}";
}
- /// What names the open page: added to the line, or to Claude's /page.
+ ///
+ /// What names the open page, by its text twin (PageTwin), at the end of a line: the twin to
+ /// read, beside the page to edit. When to add it is OpenPageNote's call.
+ ///
public static string OpenNote(string? openPage) =>
- openPage is null ? "" : $" (open: `.clayo/pages/{Path.GetFileName(openPage)}`)";
+ openPage is null ? "" : $" (page open: .clayo/pages/{Path.GetFileName(PageTwin.PathOf(openPage))})";
///
/// Claude's own /page, written into the project (PageFolder.ClaudeCommand), so Claude reads
@@ -50,11 +53,38 @@ public static string OpenNote(string? openPage) =>
"---\n" +
"Make a Clayo page as `.clayo/page-guide.md` says: $ARGUMENTS\n\n" +
"Nothing after the colon: a page of what we just discussed. " +
- "`(open: )` at the end names the page open in Clayo.\n";
+ "`(page open: .md)` at the end names the page open in Clayo by its text twin: " +
+ "a change to the page goes in the `.html` beside it.\n";
public const string ClaudeMarker = "(written by Clayo)";
}
+///
+/// When a line sent names the open page (PagePrompt.OpenNote): the first prompt after the page
+/// is opened or changes, not every one, so the terminal stays quiet; a /page always, so a change
+/// lands on that page. Not a slash command or a shell line (`!`), where it would be an argument.
+///
+public sealed class OpenPageNote
+{
+ private (string Page, DateTime Changed)? _named;
+
+ /// The page was opened again: name it on the next prompt.
+ public void Forget() => _named = null;
+
+ /// What to add to this line, sent now with this page open, changed then; else "".
+ public string For(string line, string? page, DateTime changed)
+ {
+ if (page is null) return "";
+ if (!PagePrompt.IsCommand(line))
+ {
+ var text = line.TrimStart();
+ if (text.Length == 0 || text[0] is '/' or '!' || _named == (page, changed)) return "";
+ }
+ _named = (page, changed);
+ return PagePrompt.OpenNote(page);
+ }
+}
+
///
/// The line being typed at an agent's prompt, followed from the keys alone: the agent draws
/// its own input box and never says what is in it. Text is null once the keys can no longer be
diff --git a/src/Clayo/Pages/PageTwin.cs b/src/Clayo/Pages/PageTwin.cs
new file mode 100644
index 0000000..32a61e7
--- /dev/null
+++ b/src/Clayo/Pages/PageTwin.cs
@@ -0,0 +1,340 @@
+using System.IO;
+using System.Net;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using System.Text.RegularExpressions;
+
+namespace CcxShell.Core;
+
+///
+/// A page's text twin (D18): `.md` beside `.html`, made by Clayo whenever the page
+/// changes, so another session reads the page without parsing HTML and the agent writes nothing
+/// more. Headings and text as markdown, tables as tables, a chart's data as a table, Mermaid as
+/// a mermaid block, a deck's slides between `---`. No WPF.
+///
+public static partial class PageTwin
+{
+ /// The list of a folder's pages and their twins (IndexFile), rewritten with the index.
+ public const string IndexFile = "index.md";
+
+ /// The twin's path: the page's with .md, except index.html's, which would be the list.
+ public static string PathOf(string page) =>
+ Path.GetFileNameWithoutExtension(page).Equals("index", StringComparison.OrdinalIgnoreCase)
+ ? page + ".md" : Path.ChangeExtension(page, ".md");
+
+ /// Writes the twin when it is missing or older than the page.
+ public static void Update(string page)
+ {
+ try
+ {
+ var twin = PathOf(page);
+ if (!File.Exists(page) || File.Exists(twin) && File.GetLastWriteTimeUtc(twin) >= File.GetLastWriteTimeUtc(page)) return;
+ File.WriteAllText(twin, Make(File.ReadAllText(page), Path.GetFileName(page), File.GetLastWriteTime(page)));
+ }
+ catch (Exception e) when (e is IOException or UnauthorizedAccessException) { }
+ }
+
+ /// Deletes the twin of a page that is gone.
+ public static void Delete(string page)
+ {
+ try { File.Delete(PathOf(page)); }
+ catch (Exception e) when (e is IOException or UnauthorizedAccessException) { }
+ }
+
+ ///
+ /// Writes a folder's index.md: one line per page, last changed first, or deletes it when the
+ /// folder has none left.
+ ///
+ public static void WriteIndex(string folder, IEnumerable pages)
+ {
+ var file = Path.Combine(folder, IndexFile);
+ try
+ {
+ var lines = pages.Where(p => File.Exists(p.Path)).OrderByDescending(p => File.GetLastWriteTimeUtc(p.Path))
+ .Select(p => $"- {p.Title}: `{Path.GetFileName(PathOf(p.Path))}` (page `{Path.GetFileName(p.Path)}`), changed {File.GetLastWriteTime(p.Path):yyyy-MM-dd HH:mm}")
+ .ToList();
+ if (lines.Count == 0) { File.Delete(file); return; }
+ if (!Directory.Exists(folder)) return;
+ File.WriteAllText(file, "# Pages\n\nEach page's text is in its `.md` twin: read that, not the `.html`.\n\n" + string.Join("\n", lines) + "\n");
+ }
+ catch (Exception e) when (e is IOException or UnauthorizedAccessException) { }
+ }
+
+ /// The twin of a page's HTML: its title first, then a line naming the file and when it was written.
+ public static string Make(string html, string file, DateTime written)
+ {
+ var root = Parse(html.ReplaceLineEndings("\n"));
+ var title = Find(root, n => n.Tag == "title") is { } t ? Squash(Decode(Raw(t))) : "";
+ if (title.Length == 0) title = Path.GetFileNameWithoutExtension(file);
+ var main = Find(root, n => n.Tag == "main") ?? Find(root, n => n.Tag == "body") ?? root;
+
+ var md = new Md(title);
+ string body;
+ if (Has(main, "deck"))
+ body = string.Join("\n\n---\n\n", main.Kids.OfType().Where(n => Has(n, "slide"))
+ .Select(slide => { var blocks = new List(); md.Container(slide, blocks); return string.Join("\n\n", blocks); }));
+ else
+ {
+ var blocks = new List();
+ md.Container(main, blocks);
+ body = string.Join("\n\n", blocks);
+ }
+ return $"# {title}\n\n`.clayo/pages/{file}` · written {written:yyyy-MM-dd HH:mm}\n\n{body}\n";
+ }
+
+ // A small tree: enough for the markup the guide and templates use. Kids are strings or nodes.
+ private sealed class Node(string tag, string attrs)
+ {
+ public readonly string Tag = tag;
+ public readonly string Attrs = attrs;
+ public readonly List