added example capability to website

Author: PredictabilityAtScale

.capabilities/docs/project/readme.capability.yaml

@@ -18,6 +18,9 @@ acceptance:
     after AI-assisted coding.
   - README explains capability diff, implementation coverage assessment, and
     dependency impact workflows.
+  - Website shows the hierarchical nature of the .capabilities folder.
+  - Website shows the main human-authored parts of a capability without the
+    agent section.
 guidance:
   - Keep the docs CLI-first and repo-native.
   - Do not position the MVP as a cloud product.

website/index.html

@@ -181,6 +181,70 @@ <h2>What else may break?</h2>
         </div>
       </section>
 
+      <section class="section section-alt">
+        <div class="container capability-structure-grid">
+          <div>
+            <p class="eyebrow">Repo-native structure</p>
+            <h2>The capability map is hierarchical before it is a graph.</h2>
+            <p>
+              Capability files live in `.capabilities/` using folders that mirror ownership, product areas, or platform layers.
+              The hierarchy gives reviewers a readable map before they inspect dependency edges.
+            </p>
+          </div>
+          <pre class="tree-card" aria-label="Example .capabilities folder tree"><code>.capabilities/
+  capabilitykit.yaml
+  core/
+    model/
+      define-capability-format.capability.yaml
+    validation/
+      validate-capability-files.capability.yaml
+      detect-verification-gaps.capability.yaml
+    graph/
+      compile-capabilities.capability.yaml
+      diff-capabilities.capability.yaml
+      analyze-capability-impact.capability.yaml
+    assessment/
+      assess-implementation-coverage.capability.yaml
+  developer-experience/
+    cli/
+    skills/
+  docs/
+    project/
+    reference/</code></pre>
+        </div>
+      </section>
+
+      <section class="section">
+        <div class="container capability-structure-grid">
+          <div>
+            <p class="eyebrow">Capability anatomy</p>
+            <h2>The human-facing fields describe the contract.</h2>
+            <p>
+              The top-level capability fields capture identity, current state, purpose, reviewer guidance, and acceptance criteria.
+              Agent-maintained references and verification can live below this, but the first thing a reviewer should see is the
+              product behavior being claimed.
+            </p>
+          </div>
+          <pre class="code-card"><code>id: core/graph/diff-capabilities
+title: Diff capabilities
+status: implemented
+area: core
+summary: Compare current capability files with a Git base and summarize added,
+  changed, and removed capabilities.
+intent: Help developers understand product and agent-facing intent changes
+  without reading raw YAML diffs.
+acceptance:
+  - Compares current capabilities against a configurable Git base ref.
+  - Reports added, changed, and removed capabilities by capability ID.
+  - Summarizes meaningful field changes such as status, intent, acceptance,
+    dependencies, implementation references, verification, and ignore policy.
+  - Includes downstream impact context for changed capabilities.
+guidance:
+  - Compare normalized parsed capabilities, not raw YAML text.
+  - Avoid raw JSON in the default human output.</code></pre>
+        </div>
+      </section>
+
       <section class="section graph-section">
         <div class="container graph-grid">
           <div>
@@ -203,35 +267,6 @@ <h2>Small changes can have wide capability impact.</h2>
         </div>
       </section>
 
-      <section class="section section-alt">
-        <div class="container example-grid">
-          <div>
-            <p class="eyebrow">Repo-native contract</p>
-            <h2>A capability file carries intent and review evidence together.</h2>
-            <p>
-              CapabilityKit does not replace source code, tests, or architecture decisions. It keeps the capability contract close
-              enough to the implementation that humans and agents can review whether the product behavior is still true.
-            </p>
-          </div>
-          <pre class="code-card"><code>id: core/graph/diff-capabilities
-intent: Help developers understand product and agent-facing intent changes.
-acceptance:
-  - Summarizes meaningful field changes.
-  - Includes downstream impact context.
-agent:
-  depends_on:
-    - core/graph/compile-capabilities
-  implementation:
-    references:
-      - packages/core/src/capabilityDiff.ts
-  verification:
-    automated:
-      - command: npm test -- packages/core/tests/capabilityDiff.test.ts
-    manual:
-      - Confirm the diff explains intent better than git diff.</code></pre>
-        </div>
-      </section>
-
       <section id="get-started" class="section final-cta">
         <div class="container cta-panel">
           <div>

website/styles.css

@@ -336,6 +336,7 @@ code {
 
 .steps,
 .three-panel,
+.capability-structure-grid,
 .graph-grid,
 .example-grid,
 .split {
@@ -374,6 +375,7 @@ code {
 }
 
 .split,
+.capability-structure-grid,
 .graph-grid,
 .example-grid {
   grid-template-columns: minmax(0, 0.9fr) minmax(0, 1.1fr);
@@ -424,6 +426,7 @@ li {
 }
 
 .graph-visual {
+  --graph-node-width: 10.8rem;
   position: relative;
   min-height: 430px;
   border: 1px solid var(--line);
@@ -437,7 +440,7 @@ li {
   z-index: 2;
   display: grid;
   place-items: center;
-  width: 12.4rem;
+  width: var(--graph-node-width);
   min-height: 4.2rem;
   padding: 0.8rem;
   border: 1px solid var(--line);
@@ -450,32 +453,33 @@ li {
 }
 
 .foundation {
-  left: 2rem;
-  top: 10.5rem;
+  left: 5%;
+  top: 10.7rem;
   border-top: 4px solid var(--brand);
 }
 
 .center {
-  left: calc(50% - 6.2rem);
-  top: 10.5rem;
+  left: 50%;
+  top: 10.7rem;
+  transform: translateX(-50%);
   border-top: 4px solid var(--amber);
 }
 
 .upper {
-  right: 2rem;
-  top: 3rem;
+  right: 5%;
+  top: 3.5rem;
   border-top: 4px solid var(--rose);
 }
 
 .middle {
-  right: 2rem;
-  top: 10.5rem;
+  right: 5%;
+  top: 10.7rem;
   border-top: 4px solid var(--blue);
 }
 
 .lower {
-  right: 2rem;
-  bottom: 3rem;
+  right: 5%;
+  top: 17.9rem;
   border-top: 4px solid var(--brand);
 }
 
@@ -487,15 +491,15 @@ li {
 }
 
 .edge-one {
-  left: 14.4rem;
-  right: calc(50% + 6.2rem);
-  top: 12.6rem;
+  left: calc(5% + var(--graph-node-width));
+  right: calc(50% + (var(--graph-node-width) / 2));
+  top: 12.8rem;
 }
 
 .edge-two {
-  left: calc(50% + 6.2rem);
-  right: 14.4rem;
-  top: 12.6rem;
+  left: calc(50% + (var(--graph-node-width) / 2));
+  right: calc(5% + var(--graph-node-width));
+  top: 12.8rem;
 }
 
 .edge-two::before,
@@ -504,7 +508,7 @@ li {
   position: absolute;
   right: 0;
   width: 2px;
-  height: 7.5rem;
+  height: 7.2rem;
   background: var(--line);
 }
 
@@ -520,6 +524,19 @@ li {
   box-shadow: none;
 }
 
+.tree-card {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: #fff;
+  color: var(--ink);
+  box-shadow: 0 14px 34px rgba(20, 33, 28, 0.06);
+}
+
+.tree-card code {
+  color: var(--brand-dark);
+  font-weight: 700;
+}
+
 .final-cta {
   padding-bottom: 5.5rem;
 }
@@ -566,6 +583,7 @@ li {
   .hero-grid,
   .intro-grid,
   .split,
+  .capability-structure-grid,
   .graph-grid,
   .example-grid,
   .cta-panel {