fix: reorder collection page sections and add layout to docs page

- Move use cases section above scenarios section on collection detail pages
- Add AppHeader and AppFooter to /docs/developers/guide page for consistent layout

apps/web/src/app/(profile)/[username]/collections/[slug]/CollectionDetailClient.tsx

@@ -393,6 +393,16 @@ export function CollectionDetailClient({
             </div>
           )}
 
+          {/* Use Cases Section */}
+          {collection.tools.length > 0 && (
+            <UseCasesSection
+              collectionId={collection.id}
+              useCases={collection.useCases}
+              generatedAt={collection.useCasesGeneratedAt}
+              onUseCasesGenerated={handleUseCasesGenerated}
+            />
+          )}
+
           {/* Scenarios Section */}
           {collection.tools.length > 0 && (
             <ScenariosSection
@@ -402,16 +412,6 @@ export function CollectionDetailClient({
               slug={collection.slug}
             />
           )}
-
-          {/* Use Cases Section - at the bottom */}
-          {collection.tools.length > 0 && (
-            <UseCasesSection
-              collectionId={collection.id}
-              useCases={collection.useCases}
-              generatedAt={collection.useCasesGeneratedAt}
-              onUseCasesGenerated={handleUseCasesGenerated}
-            />
-          )}
         </div>
       </main>
     </div>

apps/web/src/app/docs/developers/guide/page.tsx

@@ -3,6 +3,9 @@ import { CodeBlock } from '@tpmjs/ui/CodeBlock/CodeBlock';
 import type { Metadata } from 'next';
 import Link from 'next/link';
 
+import { AppFooter } from '~/components/AppFooter';
+import { AppHeader } from '~/components/AppHeader';
+
 export const metadata: Metadata = {
   title: 'Developers Guide | TPMJS Docs',
   description:
@@ -11,14 +14,18 @@ export const metadata: Metadata = {
 
 export default function DevelopersGuidePage(): React.ReactElement {
   return (
-    <div className="space-y-8">
+    <div className="min-h-screen bg-background flex flex-col">
+      <AppHeader />
+
+      <main className="flex-1">
+        <div className="max-w-4xl mx-auto px-4 py-12 space-y-8">
           {/* Introduction */}
           <div>
             <h1 className="text-3xl font-bold mb-4">Developers Guide: Scenarios</h1>
             <p className="text-foreground-secondary text-lg">
-          Scenarios are TPMJS&apos;s AI-powered testing and evaluation system for tool collections.
+              Scenarios are TPMJS&apos;s AI-powered testing and evaluation system for tool
-          They provide automated testing, quality tracking, and regression prevention for your
+              collections. They provide automated testing, quality tracking, and regression
-          tools.
+              prevention for your tools.
             </p>
           </div>
 
@@ -32,9 +39,9 @@ export default function DevelopersGuidePage(): React.ReactElement {
             </CardHeader>
             <CardContent className="space-y-4">
               <p className="text-foreground-secondary">
-            A Scenario is a test case that simulates how a real user would interact with your tool
+                A Scenario is a test case that simulates how a real user would interact with your
-            collection. Unlike traditional unit tests that verify individual functions, scenarios
+                tool collection. Unlike traditional unit tests that verify individual functions,
-            exercise your tools end-to-end with realistic prompts and assertions.
+                scenarios exercise your tools end-to-end with realistic prompts and assertions.
               </p>
 
               <div className="bg-background-secondary p-4 rounded-lg space-y-3">
@@ -45,16 +52,16 @@ export default function DevelopersGuidePage(): React.ReactElement {
                     collection&apos;s tools
                   </li>
                   <li>
-                <strong>Realistic Prompt:</strong> The agent executes your scenario&apos;s prompt
+                    <strong>Realistic Prompt:</strong> The agent executes your scenario&apos;s
-                against the tools
+                    prompt against the tools
                   </li>
                   <li>
                     <strong>LLM Evaluation:</strong> An LLM analyzes whether the task was completed
                     successfully
                   </li>
                   <li>
-                <strong>Result Recording:</strong> All results are stored for quality tracking and
+                    <strong>Result Recording:</strong> All results are stored for quality tracking
-                historical analysis
+                    and historical analysis
                   </li>
                 </ul>
               </div>
@@ -84,8 +91,8 @@ export default function DevelopersGuidePage(): React.ReactElement {
                 <div className="bg-background-secondary p-4 rounded-lg">
                   <h4 className="font-semibold mb-2">🎯 AI-Powered Validation</h4>
                   <p className="text-foreground-secondary text-sm">
-                Use LLM evaluation to verify your tools actually solve real problems, not just pass
+                    Use LLM evaluation to verify your tools actually solve real problems, not just
-                code tests.
+                    pass code tests.
                   </p>
                 </div>
                 <div className="bg-background-secondary p-4 rounded-lg">
@@ -107,24 +114,24 @@ export default function DevelopersGuidePage(): React.ReactElement {
                 <h4 className="font-semibold mb-3">When to Use Scenarios</h4>
                 <ul className="space-y-2 text-foreground-secondary">
                   <li>
-                <strong>Multi-Tool Integration:</strong> Testing how multiple tools work together in
+                    <strong>Multi-Tool Integration:</strong> Testing how multiple tools work
-                complex workflows
+                    together in complex workflows
                   </li>
                   <li>
-                <strong>API-First Tools:</strong> Validating tools that make HTTP requests or parse
+                    <strong>API-First Tools:</strong> Validating tools that make HTTP requests or
-                unstructured data
+                    parse unstructured data
                   </li>
                   <li>
-                <strong>Quality-Critical Collections:</strong> When tool reliability impacts user
+                    <strong>Quality-Critical Collections:</strong> When tool reliability impacts
-                experience
+                    user experience
                   </li>
                   <li>
-                <strong>Regression Prevention:</strong> Before deploying changes that might break
+                    <strong>Regression Prevention:</strong> Before deploying changes that might
-                existing functionality
+                    break existing functionality
                   </li>
                   <li>
-                <strong>Documentation-Driven Testing:</strong> Ensuring tools work as described in
+                    <strong>Documentation-Driven Testing:</strong> Ensuring tools work as described
-                their public documentation
+                    in their public documentation
                   </li>
                 </ul>
               </div>
@@ -167,9 +174,9 @@ export default function DevelopersGuidePage(): React.ReactElement {
               <div>
                 <h4 className="font-semibold mb-3">2. Agent Execution</h4>
                 <p className="text-foreground-secondary mb-2">
-              When a scenario runs, an ephemeral AI agent is created with your tool collection. The
+                  When a scenario runs, an ephemeral AI agent is created with your tool collection.
-              agent executes the scenario prompt using only the tools in that collection—no external
+                  The agent executes the scenario prompt using only the tools in that collection—no
-              access, no additional context.
+                  external access, no additional context.
                 </p>
                 <CodeBlock
                   code={`Scenario: "Extract user emails"
@@ -187,9 +194,9 @@ Collection: ["json-parser", "data-validator"]
               <div>
                 <h4 className="font-semibold mb-3">3. LLM Evaluation</h4>
                 <p className="text-foreground-secondary mb-2">
-              After execution, a powerful LLM evaluates the results. This isn&apos;t just checking
+                  After execution, a powerful LLM evaluates the results. This isn&apos;t just
-              for errors—it uses natural language understanding to verify the task was completed
+                  checking for errors—it uses natural language understanding to verify the task was
-              correctly.
+                  completed correctly.
                 </p>
                 <CodeBlock
                   code={`EVALUATION PROMPT:
@@ -227,7 +234,9 @@ Execution Time: 2.3s`}
                     </ul>
                   </div>
                   <div className="bg-red-500/10 p-4 rounded-lg">
-                <h5 className="font-semibold text-red-600 dark:text-red-400 mb-2">⚠️ On Failure</h5>
+                    <h5 className="font-semibold text-red-600 dark:text-red-400 mb-2">
+                      ⚠️ On Failure
+                    </h5>
                     <ul className="space-y-1 text-foreground-secondary text-sm">
                       <li>-20% base penalty</li>
                       <li>-5% penalty per consecutive fail</li>
@@ -236,9 +245,9 @@ Execution Time: 2.3s`}
                   </div>
                 </div>
                 <p className="text-foreground-secondary text-sm mt-4">
-              <strong>Example:</strong> A scenario that passes 5 times consecutively earns 25% bonus
+                  <strong>Example:</strong> A scenario that passes 5 times consecutively earns 25%
-              (50% + 5×5) for a total score of ~75%. High-quality scenarios (75%+) are featured on
+                  bonus (50% + 5×5) for a total score of ~75%. High-quality scenarios (75%+) are
-              the TPMJS homepage showcase.
+                  featured on the TPMJS homepage showcase.
                 </p>
               </div>
 
@@ -250,8 +259,8 @@ Execution Time: 2.3s`}
                 </p>
                 <ul className="space-y-2 text-foreground-secondary ml-4">
                   <li>
-                <strong>Full Transparency:</strong> See exactly what the agent asked and how each
+                    <strong>Full Transparency:</strong> See exactly what the agent asked and how
-                tool responded
+                    each tool responded
                   </li>
                   <li>
                     <strong>Debugging:</strong> Inspect tool inputs, outputs, and errors in detail
@@ -281,8 +290,8 @@ Execution Time: 2.3s`}
               <div className="border-l-4 border-border pl-4">
                 <h4 className="font-semibold mb-2">🚀 CI/CD Integration</h4>
                 <p className="text-foreground-secondary text-sm mb-3">
-              Automate scenario testing in your deployment pipeline to catch regressions before they
+                  Automate scenario testing in your deployment pipeline to catch regressions before
-              reach production.
+                  they reach production.
                 </p>
                 <CodeBlock
                   code={`name: Run Scenarios in CI
@@ -313,16 +322,16 @@ jobs:
                   showCopy={true}
                 />
                 <p className="text-foreground-secondary text-sm mt-2">
-              <strong>Benefits:</strong> Block deploys on failures, generate test reports, and track
+                  <strong>Benefits:</strong> Block deploys on failures, generate test reports, and
-              quality metrics over time.
+                  track quality metrics over time.
                 </p>
               </div>
 
               <div className="border-l-4 border-border pl-4">
                 <h4 className="font-semibold mb-2">🔍 Local Development Testing</h4>
                 <p className="text-foreground-secondary text-sm mb-3">
-              Test scenarios locally during development to verify tool behavior without consuming
+                  Test scenarios locally during development to verify tool behavior without
-              quota.
+                  consuming quota.
                 </p>
                 <CodeBlock
                   code={`# Generate scenarios for your tool collection
@@ -351,8 +360,8 @@ tpm scenario info clu123abc456 --json > analysis.json`}
               <div className="border-l-4 border-border pl-4">
                 <h4 className="font-semibold mb-2">📊 Quality Monitoring Dashboard</h4>
                 <p className="text-foreground-secondary text-sm mb-3">
-              Use scenario results to build dashboards showing tool reliability, success rates, and
+                  Use scenario results to build dashboards showing tool reliability, success rates,
-              performance trends.
+                  and performance trends.
                 </p>
                 <CodeBlock
                   code={`# Export scenario results as JSON
@@ -380,8 +389,8 @@ curl -X POST https://your-monitoring.com/webhook \\
               <div className="border-l-4 border-border pl-4">
                 <h4 className="font-semibold mb-2">🎓 Tool Library Development</h4>
                 <p className="text-foreground-secondary text-sm mb-3">
-              Ensure your tools work correctly with scenarios before publishing them. High-quality
+                  Ensure your tools work correctly with scenarios before publishing them.
-              scenarios increase tool visibility on the TPMJS homepage.
+                  High-quality scenarios increase tool visibility on the TPMJS homepage.
                 </p>
                 <CodeBlock
                   code={`# Create comprehensive scenario suite
@@ -413,7 +422,9 @@ Quality metrics attract more users and increase adoption.`}
                   <thead>
                     <tr className="border-b border-border">
                       <th className="text-left py-3 px-4 font-semibold text-foreground">Feature</th>
-                  <th className="text-left py-3 px-4 font-semibold text-foreground">Unit Tests</th>
+                      <th className="text-left py-3 px-4 font-semibold text-foreground">
+                        Unit Tests
+                      </th>
                       <th className="text-left py-3 px-4 font-semibold text-foreground">
                         Integration Tests
                       </th>
@@ -464,14 +475,18 @@ Quality metrics attract more users and increase adoption.`}
                       <td className="py-3 px-4 text-foreground-secondary">
                         Brittle with implementation changes
                       </td>
-                  <td className="py-3 px-4 text-foreground-secondary">Better with refactoring</td>
+                      <td className="py-3 px-4 text-foreground-secondary">
+                        Better with refactoring
+                      </td>
                       <td className="py-3 px-4 text-foreground">Self-healing with AI prompts</td>
                     </tr>
                     <tr>
                       <td className="py-3 px-4 text-foreground-secondary">
                         <strong>Debugging</strong>
                       </td>
-                  <td className="py-3 px-4 text-foreground-secondary">Stack traces, breakpoints</td>
+                      <td className="py-3 px-4 text-foreground-secondary">
+                        Stack traces, breakpoints
+                      </td>
                       <td className="py-3 px-4 text-foreground-secondary">
                         Network logs, service logs
                       </td>
@@ -525,8 +540,8 @@ Quality metrics attract more users and increase adoption.`}
               <div>
                 <h4 className="font-semibold mb-2">🚀 CI/CD Integration</h4>
                 <p className="text-foreground-secondary text-sm mb-3">
-              Automate scenario testing in your deployment pipeline to catch regressions before they
+                  Automate scenario testing in your deployment pipeline to catch regressions before
-              reach production.
+                  they reach production.
                 </p>
                 <CodeBlock
                   code={`# Simple CI/CD example
@@ -538,8 +553,8 @@ echo "All scenarios ran"`}
                   showCopy={true}
                 />
                 <p className="text-foreground-secondary text-sm mt-2">
-              <strong>Benefits:</strong> Block deploys on failures, generate test reports, and track
+                  <strong>Benefits:</strong> Block deploys on failures, generate test reports, and
-              quality metrics over time.
+                  track quality metrics over time.
                 </p>
               </div>
 
@@ -554,8 +569,8 @@ echo "All scenarios ran"`}
               <div>
                 <h4 className="font-semibold mb-2">🔌 Scenario Marketplace</h4>
                 <p className="text-foreground-secondary text-sm">
-              Share high-quality scenarios across organizations, enabling collaborative testing and
+                  Share high-quality scenarios across organizations, enabling collaborative testing
-              faster scenario coverage for popular tools.
+                  and faster scenario coverage for popular tools.
                 </p>
               </div>
 
@@ -563,8 +578,8 @@ echo "All scenarios ran"`}
                 <h4 className="font-semibold mb-3">Vision</h4>
                 <p className="text-foreground-secondary text-sm">
                   Scenarios will become the de facto standard for tool quality assurance on TPMJS.
-              Before users install a tool, they&apos;ll see its scenario history, quality scores,
+                  Before users install a tool, they&apos;ll see its scenario history, quality
-              and real-world performance metrics.
+                  scores, and real-world performance metrics.
                 </p>
               </div>
             </CardContent>
@@ -648,7 +663,10 @@ tpm scenario info clu123abc456
             <CardContent className="space-y-4">
               <ul className="space-y-3">
                 <li>
-              <Link href="/docs/api/scenarios" className="text-primary hover:underline font-medium">
+                  <Link
+                    href="/docs/api/scenarios"
+                    className="text-primary hover:underline font-medium"
+                  >
                     Scenarios API Reference →
                   </Link>
                   <p className="text-foreground-secondary text-sm">
@@ -686,5 +704,9 @@ tpm scenario info clu123abc456
             </CardContent>
           </Card>
         </div>
+      </main>
+
+      <AppFooter />
+    </div>
   );
 }