@polymorphism-tech/morph-spec 8.38.0 → 8.41.0

package/src/dashboard/app/pages/Features.jsx

@@ -0,0 +1,400 @@
+import { useEffect, useRef, useState } from 'react';
+import { Link, useParams } from 'react-router-dom';
+import {
+  CheckCircle, XCircle, CircleDashed, GitBranch, Archive, HouseSimple, CaretRight, MagnifyingGlass, WarningCircle,
+  Rows, Kanban, PauseCircle,
+} from '@phosphor-icons/react';
+import PhaseRail from '../components/PhaseRail.jsx';
+import { useMorphQuery } from '../hooks/useMorphQuery.js';
+import { usePref, useNow } from '../hooks/usePref.js';
+import { PHASES, phaseMeta, LOCATION_LABEL } from '../lib/phases.js';
+import { timeAgo } from '../lib/format.js';
+import { apiBase, featureHref } from '../lib/project.js';
+import { isFinished } from '../../scanner/feature-status.js';
+
+const COMPLETED_PAGE = 30;
+const BOARD_DONE_LIMIT = 8;
+/** An event this recent means an agent is working on the feature right now. */
+export const WORKING_MS = 3 * 60 * 1000;
+
+const LOCATION_ICON = { worktree: GitBranch, archive: Archive, root: HouseSimple };
+const SORTS = {
+  updated: { label: 'Mais recentes', cmp: (a, b) => (lastTouch(b) || '').localeCompare(lastTouch(a) || '') },
+  name: { label: 'Nome', cmp: (a, b) => a.name.localeCompare(b.name) },
+  score: { label: 'Score', cmp: (a, b) => (b.score ?? b.legacyScore ?? -1) - (a.score ?? a.legacyScore ?? -1) },
+};
+
+function lastTouch(f) {
+  const a = f.lastActivity?.ts || '';
+  const b = f.updatedAt || '';
+  return a > b ? a : b;
+}
+export function isWorking(f, now = Date.now()) {
+  const t = Date.parse(f.lastActivity?.ts || '');
+  return !isFinished(f) && !Number.isNaN(t) && now - t < WORKING_MS;
+}
+
+function VerifyMark({ verification }) {
+  if (!verification?.status) return <CircleDashed weight="light" className="text-[var(--color-faint)]" size={16} aria-label="sem verify" />;
+  return verification.status === 'pass'
+    ? <CheckCircle weight="light" className="text-[var(--color-ok)]" size={16} aria-label="último verify passou" />
+    : <XCircle weight="light" className="text-[var(--color-bad)]" size={16} aria-label="último verify falhou" />;
+}
+
+function TaskMeter({ tasks, wide = false }) {
+  if (!tasks?.total) return <span className="text-xs text-[var(--color-faint)]">sem tasks</span>;
+  const pct = Math.round((tasks.done / tasks.total) * 100);
+  return (
+    <div className="flex items-center gap-2" title={`${tasks.done} de ${tasks.total} tasks concluídas`}>
+      <div className={`h-1 overflow-hidden rounded-full bg-white/[0.07] ${wide ? 'flex-1' : 'w-12'}`}>
+        <div className="h-full rounded-full bg-[var(--color-fg)]/70" style={{ width: `${pct}%` }} />
+      </div>
+      <span className="font-mono text-xs tabular-nums text-[var(--color-dim)]">{tasks.done}/{tasks.total}</span>
+    </div>
+  );
+}
+
+function WorkingDot() {
+  return (
+    <span className="relative inline-flex h-2 w-2 shrink-0" title="o agente está trabalhando agora" aria-label="trabalhando agora">
+      <span className="absolute inset-0 animate-ping rounded-full bg-[var(--color-phase-implement)] opacity-60 motion-reduce:hidden" />
+      <span className="relative h-2 w-2 rounded-full bg-[var(--color-phase-implement)]" />
+    </span>
+  );
+}
+
+export function stageText(f) {
+  if (f.status === 'completed') return 'Concluída';
+  if (f.status === 'abandoned') return 'Abandonada';
+  if (f.location === 'archive') return 'Arquivada';
+  const paused = f.gates.find((g) => g.paused);
+  if (paused) return `Esperando você no gate de ${phaseMeta(paused.gate).label.toLowerCase()}`;
+  if (f.inEvaluation) return 'Em avaliação independente';
+  return phaseMeta(f.phase).label;
+}
+
+/** The second line of a feature: what just happened while it is live, else where it stands. */
+function subline(f, now) {
+  if (!isFinished(f) && f.lastActivity?.title) {
+    return <>{isWorking(f, now) && <WorkingDot />}<span className="truncate">{f.lastActivity.title}, {timeAgo(f.lastActivity.titleTs, now)}</span></>;
+  }
+  return <span className="truncate">{stageText(f)}{f.description ? `. ${f.description}` : ''}</span>;
+}
+
+export function FeatureRow({ f, now, project, projectName }) {
+  const LocIcon = LOCATION_ICON[f.location] || HouseSimple;
+  const score = f.score ?? f.legacyScore;
+  return (
+    <li>
+      <Link
+        to={featureHref(project, f.name)}
+        className="group fluid grid grid-cols-1 gap-3 px-5 py-4 transition-colors hover:bg-white/[0.025] md:grid-cols-[minmax(0,1fr)_14rem_6.5rem_1.5rem_2.5rem_6.5rem_1.75rem] md:items-center md:gap-5"
+      >
+        <div className="min-w-0">
+          <div className="flex items-center gap-2">
+            <span className="truncate font-medium text-[var(--color-fg)]">{f.name}</span>
+            {projectName && <span className="shrink-0 text-xs text-[var(--color-faint)]">{projectName}</span>}
+            {f.workType && f.workType !== 'feature' && (
+              <span className="shrink-0 rounded-full px-2 py-px text-[11px] text-[var(--color-dim)] shadow-[inset_0_0_0_1px_var(--color-hair-strong)]">{f.workType}</span>
+            )}
+            {f.rootStale && (
+              <WarningCircle weight="light" size={15} className="shrink-0 text-[var(--color-warn)]" aria-label="cópia da raiz possivelmente desatualizada" />
+            )}
+          </div>
+          <p className="mt-0.5 flex items-center gap-2 text-sm text-[var(--color-dim)]">{subline(f, now)}</p>
+        </div>
+        <PhaseRail feature={f} />
+        {/* One line on a phone; on desktop the wrapper dissolves into the row's grid. */}
+        <div className="flex items-center gap-5 md:contents">
+          <TaskMeter tasks={f.tasks} />
+          <VerifyMark verification={f.verification} />
+          <span className="font-mono text-sm tabular-nums text-[var(--color-dim)]" title={score != null ? 'score do avaliador' : 'sem score'}>
+            {score != null ? score : '—'}
+          </span>
+          <span className="flex items-center gap-1.5 text-xs text-[var(--color-faint)]" title={LOCATION_LABEL[f.location]}>
+            <LocIcon weight="light" size={14} />
+            {timeAgo(lastTouch(f), now)}
+          </span>
+        </div>
+        <span className="fluid hidden h-7 w-7 items-center justify-center rounded-full bg-white/[0.04] text-[var(--color-dim)] transition-transform group-hover:translate-x-0.5 group-hover:bg-white/[0.08] group-hover:text-[var(--color-fg)] md:flex">
+          <CaretRight weight="light" size={14} />
+        </span>
+      </Link>
+    </li>
+  );
+}
+
+export function Section({ title, hint, features, now, project }) {
+  return (
+    <section>
+      <div className="mb-3 flex items-baseline justify-between px-1">
+        <h2 className="text-sm font-medium text-[var(--color-fg)]">{title}</h2>
+        {hint && <span className="text-xs text-[var(--color-faint)]">{hint}</span>}
+      </div>
+      <div className="bezel">
+        <ul className="bezel-core divide-y divide-[var(--color-hair)] overflow-hidden">
+          {features.map((f) => <FeatureRow key={f.name} f={f} now={now} project={project} />)}
+        </ul>
+      </div>
+    </section>
+  );
+}
+
+function BoardCard({ f, now, project }) {
+  const score = f.score ?? f.legacyScore;
+  const paused = f.gates.find((g) => g.paused);
+  return (
+    <li>
+      <Link
+        to={featureHref(project, f.name)}
+        className={[
+          'fluid block rounded-xl bg-[var(--color-raised)] px-3.5 py-3 transition-[transform,box-shadow] hover:-translate-y-px active:scale-[0.99]',
+          paused ? 'shadow-[inset_0_0_0_1px_var(--color-warn)]' : 'shadow-[inset_0_0_0_1px_var(--color-hair),inset_0_1px_0_rgb(255_255_255_/_0.05)] hover:shadow-[inset_0_0_0_1px_var(--color-hair-strong)]',
+        ].join(' ')}
+      >
+        <div className="flex items-start justify-between gap-2">
+          <span className="min-w-0 break-words text-sm font-medium leading-snug text-[var(--color-fg)]">{f.name}</span>
+          {isWorking(f, now) ? <span className="mt-1.5"><WorkingDot /></span> : null}
+        </div>
+        {paused && (
+          <p className="mt-1.5 flex items-center gap-1.5 text-xs text-[var(--color-warn)]">
+            <PauseCircle weight="light" size={14} /> esperando você
+          </p>
+        )}
+        {!paused && f.inEvaluation && <p className="mt-1.5 text-xs text-[var(--color-phase-review)]">em avaliação</p>}
+        {f.lastActivity?.title && !isFinished(f) && (
+          <p className="mt-1.5 line-clamp-2 text-xs text-[var(--color-dim)]">{f.lastActivity.title}</p>
+        )}
+        <div className="mt-3"><TaskMeter tasks={f.tasks} wide /></div>
+        <div className="mt-2.5 flex items-center justify-between text-xs text-[var(--color-faint)]">
+          <span className="flex items-center gap-2">
+            <VerifyMark verification={f.verification} />
+            {score != null && <span className="font-mono tabular-nums text-[var(--color-dim)]">{score}</span>}
+            {f.workType && f.workType !== 'feature' && <span>{f.workType}</span>}
+          </span>
+          <span>{timeAgo(lastTouch(f), now)}</span>
+        </div>
+      </Link>
+    </li>
+  );
+}
+
+export function Board({ features, showDone, now, project }) {
+  const active = features.filter((f) => !isFinished(f));
+  const done = features.filter(isFinished).slice(0, BOARD_DONE_LIMIT);
+  const columns = PHASES.map((p) => ({ ...p, items: active.filter((f) => f.phase === p.id) }));
+  if (showDone) columns.push({ id: 'done', label: 'Concluídas', color: 'var(--color-ok)', items: done });
+  return (
+    <div className="-mx-4 overflow-x-auto px-4 pb-4 md:mx-0 md:px-0">
+      <div className="grid auto-cols-[16.5rem] grid-flow-col gap-3 md:auto-cols-[minmax(11rem,1fr)]">
+        {columns.map((c) => (
+          <section key={c.id} className="bezel min-w-0" aria-label={`${c.label}: ${c.items.length}`}>
+            <div className="bezel-core flex h-full min-h-[14rem] flex-col p-2.5">
+              <h2 className="flex items-center justify-between px-1.5 pb-2.5 pt-1 text-sm">
+                <span className="flex items-center gap-2 font-medium"><span className="h-2 w-2 rounded-full" style={{ background: c.color }} />{c.label}</span>
+                <span className="font-mono text-xs text-[var(--color-faint)]">{c.items.length}</span>
+              </h2>
+              {c.items.length === 0
+                ? <p className="px-1.5 text-xs text-[var(--color-faint)]">{c.id === 'done' ? 'Nada concluído ainda.' : 'Nenhuma feature aqui.'}</p>
+                : <ul className="space-y-2">{c.items.map((f) => <BoardCard key={f.name} f={f} now={now} project={project} />)}</ul>}
+            </div>
+          </section>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function Empty({ title, children }) {
+  return (
+    <div className="bezel mx-auto mt-16 max-w-lg">
+      <div className="bezel-core px-8 py-10 text-center">
+        <h2 className="text-lg font-medium">{title}</h2>
+        <div className="mt-2 text-sm leading-relaxed text-[var(--color-dim)]">{children}</div>
+      </div>
+    </div>
+  );
+}
+
+export function Segmented({ value, onChange, options, label }) {
+  return (
+    <div role="radiogroup" aria-label={label} className="inline-flex rounded-full bg-white/[0.03] p-1 shadow-[inset_0_0_0_1px_var(--color-hair)]">
+      {options.map((o) => (
+        <button
+          key={o.id}
+          type="button"
+          role="radio"
+          aria-checked={value === o.id}
+          onClick={() => onChange(o.id)}
+          className={[
+            'fluid flex items-center gap-1.5 rounded-full px-3 py-1.5 text-sm transition-colors active:scale-[0.98]',
+            value === o.id ? 'bg-white/[0.1] text-[var(--color-fg)]' : 'text-[var(--color-dim)] hover:text-[var(--color-fg)]',
+          ].join(' ')}
+        >
+          {o.icon && <o.icon weight="light" size={15} />}{o.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+const chipClass = (on) => [
+  'fluid rounded-full px-3 py-1 text-xs transition-colors active:scale-[0.98]',
+  on ? 'bg-white/[0.09] text-[var(--color-fg)] shadow-[inset_0_0_0_1px_var(--color-hair-strong)]' : 'text-[var(--color-faint)] shadow-[inset_0_0_0_1px_var(--color-hair)] hover:text-[var(--color-dim)]',
+].join(' ');
+
+/**
+ * The feature home. All state comes in as props so the view renders the same
+ * with the live API and with the smoke test's fixture.
+ */
+export function FeaturesView({
+  data, query, onQuery, completedShown, onShowMore,
+  view = 'list', onView = () => {}, types = [], onTypes = () => {}, sort = 'updated', onSort = () => {},
+  showDone = true, onShowDone = () => {}, now = Date.now(), searchRef, project,
+}) {
+  const { project: info, features } = data;
+  const q = query.trim().toLowerCase();
+  const presentTypes = [...new Set(features.map((f) => f.workType || 'feature'))].sort();
+  const visible = features
+    .filter((f) => !q || f.name.toLowerCase().includes(q) || (f.description || '').toLowerCase().includes(q))
+    .filter((f) => types.length === 0 || types.includes(f.workType || 'feature'))
+    .sort(SORTS[sort]?.cmp || SORTS.updated.cmp);
+  const awaiting = visible.filter((f) => f.awaiting);
+  const active = visible.filter((f) => !f.awaiting && !isFinished(f));
+  const done = visible.filter(isFinished);
+  const working = features.filter((f) => isWorking(f, now)).length;
+
+  return (
+    <div className="mx-auto max-w-7xl px-4 pb-24 pt-10 md:px-10 md:pt-14">
+      <header className="rise mb-8">
+        <p className="text-sm text-[var(--color-dim)]">Projeto</p>
+        <h1 className="mt-1 break-words text-4xl font-semibold tracking-tight md:text-5xl">{info.name}</h1>
+        <p className="mt-3 flex flex-wrap items-center gap-x-2 text-sm text-[var(--color-dim)]">
+          {info.stack && <span>stack <span className="font-mono text-[var(--color-fg)]">{info.stack}</span>,</span>}
+          <span>trust <span className="font-mono text-[var(--color-fg)]">{info.trust || 'auto'}</span>,</span>
+          <span>{features.filter((f) => !isFinished(f)).length} ativas de {features.length}</span>
+          {working > 0 && <span className="flex items-center gap-1.5 text-[var(--color-phase-implement)]"><WorkingDot /> {working} com agente trabalhando agora</span>}
+        </p>
+      </header>
+
+      {features.length > 0 && (
+        <div className="rise-2 mb-8 flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
+          <div className="flex flex-wrap items-center gap-2">
+            <Segmented label="Visualização" value={view} onChange={onView} options={[{ id: 'list', label: 'Lista', icon: Rows }, { id: 'board', label: 'Quadro', icon: Kanban }]} />
+            {presentTypes.length > 1 && presentTypes.map((t) => (
+              <button key={t} type="button" aria-pressed={types.includes(t)} className={chipClass(types.includes(t))}
+                onClick={() => onTypes(types.includes(t) ? types.filter((x) => x !== t) : [...types, t])}>{t}</button>
+            ))}
+            {view === 'board' && (
+              <button type="button" aria-pressed={showDone} className={chipClass(showDone)} onClick={() => onShowDone(!showDone)}>concluídas recentes</button>
+            )}
+          </div>
+          <div className="flex items-center gap-2">
+            {view === 'list' && (
+              <label className="text-sm text-[var(--color-dim)]">
+                <span className="sr-only">Ordenar por</span>
+                <select value={sort} onChange={(e) => onSort(e.target.value)}
+                  className="fluid rounded-full bg-white/[0.04] px-3 py-2 text-sm text-[var(--color-fg)] shadow-[inset_0_0_0_1px_var(--color-hair)] outline-none">
+                  {Object.entries(SORTS).map(([id, s]) => <option key={id} value={id}>{s.label}</option>)}
+                </select>
+              </label>
+            )}
+            <label className="relative block w-full md:w-72">
+              <span className="sr-only">Buscar feature</span>
+              <MagnifyingGlass weight="light" size={16} className="pointer-events-none absolute left-3.5 top-1/2 -translate-y-1/2 text-[var(--color-faint)]" />
+              <input
+                ref={searchRef}
+                value={query}
+                onChange={(e) => onQuery(e.target.value)}
+                onKeyDown={(e) => { if (e.key === 'Escape') { onQuery(''); e.currentTarget.blur(); } }}
+                placeholder="Buscar feature"
+                className="fluid w-full rounded-full bg-white/[0.04] py-2 pl-10 pr-10 text-sm text-[var(--color-fg)] shadow-[inset_0_0_0_1px_var(--color-hair)] outline-none transition-shadow placeholder:text-[var(--color-faint)] focus:shadow-[inset_0_0_0_1px_var(--color-hair-strong)]"
+              />
+              <kbd className="pointer-events-none absolute right-3 top-1/2 -translate-y-1/2 rounded-md px-1.5 font-mono text-[11px] text-[var(--color-faint)] shadow-[inset_0_0_0_1px_var(--color-hair)]">/</kbd>
+            </label>
+          </div>
+        </div>
+      )}
+
+      {!info.initialized && (
+        <Empty title="Este diretório não usa morph-spec">
+          Rode <code className="font-mono text-[var(--color-fg)]">morph-spec init</code> na raiz do projeto e abra o dashboard de novo.
+        </Empty>
+      )}
+      {info.legacyStateOnly && (
+        <Empty title="Projeto no modelo de estado antigo">
+          As features deste projeto vivem só no <code className="font-mono">state.json</code>, sem <code className="font-mono">feature.json</code> por feature.
+          Rode <code className="font-mono text-[var(--color-fg)]">morph-spec update</code> para migrar.
+        </Empty>
+      )}
+      {info.initialized && !info.legacyStateOnly && features.length === 0 && (
+        <Empty title="Nenhuma feature ainda">
+          No Claude Code, comece uma com <code className="font-mono text-[var(--color-fg)]">/morph-proposal</code>. Ela aparece aqui assim que o <code className="font-mono">feature.json</code> nascer.
+        </Empty>
+      )}
+      {features.length > 0 && visible.length === 0 && (
+        <p className="px-1 text-sm text-[var(--color-dim)]">Nenhuma feature com esses filtros.</p>
+      )}
+
+      {view === 'board' && visible.length > 0 && <div className="rise-3"><Board features={visible} showDone={showDone} now={now} project={project} /></div>}
+
+      {view === 'list' && (
+        <div className="rise-3 space-y-10">
+          {awaiting.length > 0 && <Section title="Esperando você" hint="gate pausado" features={awaiting} now={now} project={project} />}
+          {active.length > 0 && <Section title="Em andamento" hint={`${active.length}`} features={active} now={now} project={project} />}
+          {done.length > 0 && (
+            <div>
+              <Section title="Concluídas" hint={`${done.length}`} features={done.slice(0, completedShown)} now={now} project={project} />
+              {done.length > completedShown && (
+                <button
+                  type="button"
+                  onClick={onShowMore}
+                  className="fluid mt-4 rounded-full px-4 py-2 text-sm text-[var(--color-dim)] shadow-[inset_0_0_0_1px_var(--color-hair)] transition-colors hover:text-[var(--color-fg)] active:scale-[0.98]"
+                >
+                  Mostrar mais {Math.min(COMPLETED_PAGE, done.length - completedShown)}
+                </button>
+              )}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default function Features() {
+  const { project } = useParams();
+  const { data, error, loading } = useMorphQuery(`${apiBase(project)}/features`, { scope: ['features', 'activity'], project });
+  const [query, setQuery] = useState('');
+  const [completedShown, setCompletedShown] = useState(COMPLETED_PAGE);
+  const [view, setView] = usePref('features.view', 'list');
+  const [types, setTypes] = usePref('features.types', []);
+  const [sort, setSort] = usePref('features.sort', 'updated');
+  const [showDone, setShowDone] = usePref('features.board.showDone', true);
+  const now = useNow();
+  const searchRef = useRef(null);
+
+  // `/` jumps to the search, like most dev tools.
+  useEffect(() => {
+    const onKey = (e) => {
+      if (e.key !== '/' || e.ctrlKey || e.metaKey || e.altKey) return;
+      const tag = document.activeElement?.tagName;
+      if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+      e.preventDefault();
+      searchRef.current?.focus();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, []);
+
+  if (error) return <Empty title="Não consegui ler as features">{error}</Empty>;
+  if (loading || !data) return <p className="px-10 pt-16 text-sm text-[var(--color-faint)]">Lendo o projeto…</p>;
+  return (
+    <FeaturesView
+      data={data} query={query} onQuery={setQuery} completedShown={completedShown}
+      onShowMore={() => setCompletedShown((n) => n + COMPLETED_PAGE)}
+      view={view} onView={setView} types={types} onTypes={setTypes} sort={sort} onSort={setSort}
+      showDone={showDone} onShowDone={setShowDone} now={now} searchRef={searchRef} project={project}
+    />
+  );
+}

package/src/dashboard/app/pages/Guide.jsx

@@ -0,0 +1,146 @@
+import { useMemo, useState } from 'react';
+import { Link, useParams } from 'react-router-dom';
+import GithubSlugger from 'github-slugger';
+import morphData from 'virtual:morph-data';
+import KnowledgeMarkdown from '../components/KnowledgeMarkdown.jsx';
+import EntityLink from '../components/EntityLink.jsx';
+import { PHASES, GATE_LABEL } from '../lib/phases.js';
+
+const GUIDE = morphData.docs?.guide || [];
+
+/** Same slugs rehype-slug gives the rendered headings, in document order. */
+export function tocOf(doc) {
+  const slugger = new GithubSlugger();
+  return (doc?.headings || []).map((h) => ({ ...h, slug: slugger.slug(h.text) }));
+}
+
+function personasIn(phaseId) {
+  return (morphData.agents?.list || []).filter((a) => a.activePhases?.includes(phaseId));
+}
+
+/** The whole flow on one screen: phase, the skill that runs it, who works in it, the gate that closes it. */
+export function Flow() {
+  return (
+    <section aria-label="O fluxo do morph-spec" className="bezel">
+      <div className="bezel-core px-5 py-6 md:px-8">
+        <h2 className="text-lg font-semibold tracking-tight">Como uma feature anda</h2>
+        <p className="mt-1 max-w-3xl text-sm leading-relaxed text-[var(--color-dim)]">
+          Você descreve o que quer; o Claude conduz cada fase com uma skill, despacha personas especialistas como sub-agents e para nos gates.
+          Com trust <span className="font-mono text-[var(--color-fg)]">auto</span>, um gate só pausa para você quando aparece um sinal de risco.
+          No fim, um avaliador independente dá a nota.
+        </p>
+        <ol className="mt-6 grid gap-3 md:grid-cols-5">
+          {PHASES.map((p) => {
+            const people = personasIn(p.id);
+            return (
+              <li key={p.id} className="relative rounded-xl bg-[var(--color-raised)] p-4 shadow-[inset_0_0_0_1px_var(--color-hair)]">
+                <span className="absolute inset-x-4 top-0 h-0.5 rounded-full" style={{ background: p.color }} />
+                <p className="flex items-baseline justify-between gap-2">
+                  <EntityLink kind="phase" id={p.id} plain className="font-medium text-[var(--color-fg)] underline-offset-2 hover:underline">{p.label}</EntityLink>
+                  {p.optional && <span className="text-xs text-[var(--color-faint)]">opcional</span>}
+                </p>
+                {p.skill && <p className="mt-2 text-xs text-[var(--color-dim)]">skill <EntityLink kind="skill" id={p.skill} className="font-mono" /></p>}
+                {people.length > 0 && (
+                  <p className="mt-2 flex flex-wrap gap-1.5">
+                    {people.map((a) => <EntityLink key={a.id} kind="persona" id={a.id} chip>{a.id}</EntityLink>)}
+                  </p>
+                )}
+                {GATE_LABEL[p.id] && (
+                  <p className="mt-3 flex items-center gap-1.5 text-xs text-[var(--color-dim)]">
+                    <span className="h-2 w-2 rounded-full ring-1 ring-[var(--color-ok)]" /> fecha no {GATE_LABEL[p.id]}
+                  </p>
+                )}
+              </li>
+            );
+          })}
+        </ol>
+      </div>
+    </section>
+  );
+}
+
+export function GuideView({ docId }) {
+  const doc = GUIDE.find((d) => d.id === docId) || GUIDE[0];
+  const toc = useMemo(() => tocOf(doc).filter((h) => h.depth >= 2), [doc]);
+  const [filter, setFilter] = useState('');
+  const q = filter.trim().toLowerCase();
+  const shown = q ? toc.filter((h) => h.text.toLowerCase().includes(q)) : toc;
+
+  return (
+    <div className="mx-auto max-w-7xl px-4 pb-24 pt-10 md:px-10 md:pt-14">
+      <header className="rise mb-8">
+        <h1 className="text-4xl font-semibold tracking-tight md:text-5xl">Guia</h1>
+        <p className="mt-3 max-w-2xl text-sm leading-relaxed text-[var(--color-dim)]">
+          O que o morph-spec instala no seu projeto e como o Claude o usa. Os nomes de skills, personas e standards citados no texto levam às páginas deles.
+        </p>
+      </header>
+
+      <div className="rise-2 mb-10"><Flow /></div>
+
+      {!doc && <p className="text-sm text-[var(--color-dim)]">Nenhum documento do framework encontrado.</p>}
+      {doc && (
+        <>
+          <nav aria-label="Documentos" className="rise-3 mb-6 grid gap-2 md:grid-cols-3">
+            {GUIDE.map((d) => {
+              const active = d.id === doc.id;
+              return (
+                <Link
+                  key={d.id}
+                  to={`/guide/${d.id}`}
+                  aria-current={active ? 'page' : undefined}
+                  className={[
+                    'fluid rounded-xl px-4 py-3 transition-colors',
+                    active ? 'bg-white/[0.07] shadow-[inset_0_0_0_1px_var(--color-hair-strong)]' : 'shadow-[inset_0_0_0_1px_var(--color-hair)] hover:bg-white/[0.03]',
+                  ].join(' ')}
+                >
+                  <p className="text-sm font-medium text-[var(--color-fg)]">{d.title}</p>
+                  <p className="mt-0.5 text-xs leading-relaxed text-[var(--color-dim)]">{d.summary}</p>
+                </Link>
+              );
+            })}
+          </nav>
+
+          <div className="grid gap-6 lg:grid-cols-[15rem_minmax(0,1fr)]">
+            <aside className="lg:sticky lg:top-4 lg:max-h-[calc(100dvh-2rem)] lg:self-start lg:overflow-y-auto">
+              <label className="mb-3 block">
+                <span className="sr-only">Filtrar seções</span>
+                <input
+                  value={filter}
+                  onChange={(e) => setFilter(e.target.value)}
+                  placeholder="Filtrar seções"
+                  className="fluid w-full rounded-full bg-white/[0.04] px-3.5 py-1.5 text-sm text-[var(--color-fg)] shadow-[inset_0_0_0_1px_var(--color-hair)] outline-none placeholder:text-[var(--color-faint)]"
+                />
+              </label>
+              <ul className="space-y-0.5 text-sm">
+                {shown.map((h) => (
+                  <li key={h.slug}>
+                    <a
+                      href={`#${h.slug}`}
+                      className={[
+                        'fluid block truncate rounded-md py-1 text-[var(--color-dim)] transition-colors hover:bg-white/[0.04] hover:text-[var(--color-fg)]',
+                        h.depth === 3 ? 'pl-5 text-xs' : 'pl-2',
+                      ].join(' ')}
+                      title={h.text}
+                    >
+                      {h.text}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </aside>
+            <div className="bezel min-w-0">
+              <div className="bezel-core min-w-0 px-6 py-8 md:px-12 md:py-10">
+                <KnowledgeMarkdown text={doc.content} />
+              </div>
+            </div>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+export default function Guide() {
+  const { doc } = useParams();
+  return <GuideView docId={doc} />;
+}