Add communication resource dropdowns including HowTo

AGENTS.md

@@ -1,7 +1,9 @@
 # PyAutoBroca
 
-Broca owns assistant evaluation records, collection receipts and the operational
-board. Brain interprets evidence and routes changes; Mind owns development state;
+Broca covers communication and documentation: documentation, tutorials, user-facing
+workspaces and assistants are first-class resources. Projects own their source.
+Broca owns communication inventory views, assistant evaluation records, collection
+receipts and the operational board. Brain interprets evidence and routes changes; Mind owns development state;
 Cortex owns science records; Heart owns readiness. Public assistants remain
 independently usable and do not depend on Broca.
 
@@ -63,3 +65,7 @@ body and hands them to the human (sessions cannot create Discussions). Only the
 development flow — Mind prompt → `/start_dev` → `/create_issue` → one issue per
 task → PR — opens issues here. Why: `PyAutoMind/policy/community_surface.md`.
 <!-- repos_sync:filing:end -->
+
+Expanded resource ownership is documented in docs/communication.md. The public
+resources.json is generated from Scientist relationships and Mind identities; do
+not hand-maintain another resource registry or infer quality from a build result.

CHECKIN.md

@@ -20,3 +20,9 @@ Brain owns interpretation. Route accepted implementation work through Mind and
 start-dev. Cortex retains science records; Heart retains readiness. Keep raw
 transcripts, credentials and private project data out of public outputs. Finish
 with the current evidence and the next action. Do not arm background monitoring.
+
+Also inspect the communication resource inventory: documentation, HowTo tutorials,
+user-facing workspaces and assistants. Start with purpose/audience and source
+ownership. Keep missing evidence unknown, separate technical validation from
+explanatory quality, and route bounded improvements through Mind. Do not run
+paid evaluations, publish or send external messages as part of this check-in.

README.md

@@ -1,8 +1,10 @@
 # PyAutoBroca
 
-Assistant evaluation history, upkeep evidence and a shared-format dashboard.
-Broca answers which assistant needs attention, what evidence supports that, and
-which evaluation would be useful next. Brain interprets; Mind tracks fixes.
+Communication and documentation resources, assistant evaluation history and upkeep evidence.
+The dashboard gives documentation, HowTo tutorials, workspaces and assistants
+their own project-linked dropdowns. Projects retain their source material;
+Brain interprets evidence and Mind tracks fixes. See the
+[communication contract](docs/communication.md) for ownership and catalogue refresh.
 
 ## Local check-in
 

broca/board.py

@@ -44,6 +44,7 @@ def render(root, brain):
     rows = {r["assistant"]: r for r in snapshot["assistants"]}
     esc = lambda value: html.escape(str(value), quote=True)
     panels, attention, history, maintenance = [], [], [], []
+    assistant_evidence = {}
     for name in cfg["assistants"]:
         row = rows.get(name, {})
         runs = sorted((r for r in records if r["assistant"] == name and r["kind"] == "benchmark"),
@@ -61,6 +62,10 @@ def render(root, brain):
                 if re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repo) else esc(name))
         when = latest["observed_at"] if latest else "No run recorded"
         revision = (row.get("revision") or "Unknown")[:12]
+        assistant_evidence[name] = {"state": state, "collection": collected,
+                                    "github": repo, "revision": revision,
+                                    "collected_at": snapshot.get("refreshed_at") or "Unknown",
+                                    "observed_at": when}
         definitions = len(row.get("benchmarks", [])) if collected != "unavailable" else "Unknown"
         panels.append(f'<article class="assistant-card"><h3>{link}</h3><p><strong>{esc(state)}</strong></p>'
                       f'<dl><dt>Latest evidence day</dt><dd>{esc(when)}</dd><dt>Runs recorded</dt><dd>{len(runs)}</dd>'
@@ -100,7 +105,10 @@ def render(root, brain):
                             f'<td>{esc(record["reason"] or "—")}<br>{esc(delta)}</td>'
                             f'<td><code>{esc(record["run_id"])}</code><br>{esc(record["source"]["path"])}</td></tr>'))
     prompt = (Path(root) / "CHECKIN.md").read_text()
-    navigation = [{"href": "#assistants", "label": "Assistants", "count": len(cfg["assistants"])},
+    from .resources import render as render_resources
+    resource_html = render_resources(root, assistant_evidence)
+    navigation = [{"href": "#communication", "label": "Communication resources"},
+                  {"href": "#assistants", "label": "Assistants", "count": len(cfg["assistants"])},
                   {"href": "#attention", "label": "Next actions"},
                   {"href": "#history", "label": "Evaluations", "count": len(history)},
                   {"href": "#maintenance", "label": "Maintenance"}]
@@ -111,13 +119,13 @@ def render(root, brain):
              '<table><thead><tr><th>Assistant / benchmark</th><th>Date / model</th><th>Outcome / score</th><th>Evidence / comparison</th><th>Record</th></tr></thead><tbody>'
              + ''.join(row for _, row in sorted(history, key=lambda item: item[0], reverse=True)) + '</tbody></table></div>') if history else '<p>No benchmark runs recorded.</p>'
     page = ('<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">'
-            '<title>PyAutoBroca · Assistants</title><style>' + theme.css("broca") + '''
+            '<title>PyAutoBroca · Communication</title><style>' + theme.css("broca") + '''
 .assistant-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,260px),1fr));gap:1rem}
 .assistant-card{border:1px solid var(--line,#888);border-radius:12px;padding:1rem;min-width:0}
 .assistant-card h3{margin-top:0}dl{display:grid;grid-template-columns:1fr 1fr;gap:.4rem}dd{margin:0}
 .table-scroll{overflow-x:auto;max-width:100%}.table-scroll table{min-width:760px;width:100%}
 th,td{text-align:left;vertical-align:top;padding:.6rem}td code{overflow-wrap:anywhere}
-</style></head><body><main>''' + theme.hero("broca", "Assistants", navigation=navigation) + panel +
+</style></head><body><main>''' + theme.hero("broca", "Communication", navigation=navigation) + panel + resource_html +
             '<section id="assistants"><h2>Assistants</h2><div class="assistant-grid">' + ''.join(panels) + '</div></section>' +
             '<section id="attention"><h2>Next actions</h2><ul>' + ''.join(attention) + '</ul></section>' +
             '<section id="history"><h2>Evaluation history</h2>' + table + '</section>' +

broca/resources.py

@@ -0,0 +1,51 @@
+"""Communication inventory projected from Scientist; never a quality verdict."""
+import html
+import json
+from pathlib import Path
+from urllib.parse import urlsplit
+
+TYPES = {'documentation': 'Documentation', 'tutorials': 'Tutorials',
+         'workspaces': 'Workspace', 'assistants': 'Assistant'}
+PURPOSE = {'documentation': 'Reference and explanations for using the software.',
+           'tutorials': 'Guided learning: start with the tutorial introduction.',
+           'workspaces': 'Runnable user examples: start with its README and setup guidance.',
+           'assistants': 'A project-owned assistant: read its scope and setup instructions.'}
+
+
+def link(url, label):
+    parsed = urlsplit(str(url))
+    if parsed.scheme != 'https' or not parsed.hostname or parsed.username or parsed.password:
+        return html.escape(str(label))
+    return f'<a href="{html.escape(str(url), quote=True)}">{html.escape(str(label))}</a>'
+
+
+def render(root, assistant_evidence):
+    path = Path(root) / 'resources.json'
+    if not path.is_file():
+        return '<section id="communication"><h2>Communication resources</h2><p>Public resource inventory unavailable.</p></section>'
+    catalogue = json.loads(path.read_text())
+    if catalogue.get('schema_version') != 1 or not isinstance(catalogue.get('resources'), list):
+        raise ValueError('invalid public resource catalogue')
+    esc = lambda value: html.escape(str(value), quote=True)
+    cards = []
+    for resource in catalogue['resources']:
+        kinds = [k for k in TYPES if k in resource.get('relations', [])]
+        if not kinds:
+            continue
+        evidence = assistant_evidence.get(resource.get('repo')) if 'assistants' in kinds else None
+        # Bind assistant evidence to the exact canonical remote, not a similar name.
+        if evidence and evidence.get('github') != resource.get('github'):
+            evidence = None
+        state = evidence['state'] if evidence else 'Inventory only — quality not evaluated'
+        projects = ', '.join(p['name'] for p in resource['projects'])
+        links = ' · '.join(link(l['url'], l['label']) for l in resource['links'])
+        details = ('<p>Collection: ' + esc(evidence['collection']) + ' · collected ' + esc(evidence['collected_at'])
+                   + '</p><p>Current commit: ' + esc(evidence['revision']) + ' · latest evaluation day: '
+                   + esc(evidence['observed_at']) + '</p>') if evidence else '<p>Revision, collection time and upkeep evidence: unavailable for this resource.</p>'
+        cards.append(f'''<details id="resource-{esc(resource['id'])}"><summary>{esc(resource['name'])} · {esc(' / '.join(TYPES[k] for k in kinds))} · {esc(projects)} · {esc(state)}</summary>
+<p>{esc(' '.join(PURPOSE[k] for k in kinds))}</p><p>{links}</p>
+<p>Used by: {esc(projects)}. Shared resources retain one identity; no assistant is required.</p>{details}
+<p>Technical validation belongs to Heart. A successful build or runnable example does not establish explanatory quality or scientific correctness.</p>
+<p>Next: inspect this resource's introduction, intended audience and known gaps with Broca before proposing a bounded documentation or evaluation task.</p></details>''')
+    return ('<section id="communication"><h2>Communication resources</h2><p>Documentation, tutorials, user workspaces and assistants. Project repositories own the source; Broca presents communication context and available upkeep evidence.</p>'
+            + ''.join(cards) + ('' if cards else '<p>No public communication resources configured.</p>') + '</section>')