docs: dedup lead paragraph, number on-this-page TOC

docs/app/components/docs/toc.tsx

@@ -101,7 +101,10 @@ export function Toc() {
             href={`#${h.id}`}
             className={`toc-link ${h.level === 3 ? "sub" : ""} ${h.id === active ? "active" : ""}`.trim()}
           >
-            {h.text}
+            {/* Top-level entries are auto-numbered by CSS counter; strip any
+                authored "N." prefix (some pages number their own headings) so
+                the number isn't shown twice. */}
+            {h.level === 2 ? h.text.replace(/^\d+[.)]\s+/, "") : h.text}
           </a>
         ))}
       </div>

docs/app/styles/docs.css

@@ -1239,6 +1239,11 @@ body {
   width: 14px;
   height: 14px;
 }
+/* Top-level entries are auto-numbered (1., 2., …) from a counter; sub-headings
+   use a dot instead (below). The counter resets per page. */
+#toc-list {
+  counter-reset: toc-section;
+}
 .toc-link {
   display: block;
   font-size: 13px;
@@ -1250,6 +1255,15 @@ body {
     border-color 0.15s;
   cursor: pointer;
 }
+.toc-link:not(.sub) {
+  counter-increment: toc-section;
+}
+.toc-link:not(.sub)::before {
+  content: counter(toc-section) ". ";
+  color: var(--dim);
+  font-family: var(--mono);
+  font-size: 11px;
+}
 .toc-link:hover {
   color: var(--txt);
 }

docs/content/docs/architecture/job-lifecycle.mdx

@@ -3,8 +3,6 @@ title: Job Lifecycle
 description: "Every job moves through a state machine from creation to completion (or death)."
 ---
 
-Every job moves through a state machine from creation to completion (or death).
-
 <JobStateMachine />
 
 ## Key transitions

docs/content/docs/java/guides/core/index.mdx

@@ -3,8 +3,6 @@ title: Core
 description: "The building blocks of every Java taskito application."
 ---
 
-The building blocks of every taskito application.
-
 <Cards>
   <Card
     title="Tasks"

docs/content/docs/java/guides/reliability/index.mdx

@@ -3,8 +3,6 @@ title: Reliability
 description: "Harden your Java task queue for production workloads."
 ---
 
-Harden your task queue for production workloads.
-
 <Cards>
   <Card
     title="Error Handling"

docs/content/docs/node/guides/core/index.mdx

@@ -3,8 +3,6 @@ title: Core
 description: "The building blocks of every Node.js taskito application."
 ---
 
-The building blocks of every taskito application.
-
 <Cards>
   <Card
     title="Tasks"

docs/content/docs/node/guides/reliability/index.mdx

@@ -3,8 +3,6 @@ title: Reliability
 description: "Harden your Node.js task queue for production workloads."
 ---
 
-Harden your task queue for production workloads.
-
 <Cards>
   <Card
     title="Error Handling"

docs/content/docs/python/api-reference/overview.mdx

@@ -3,8 +3,6 @@ title: Overview
 description: "Complete Python API reference for all public classes and methods."
 ---
 
-Complete Python API reference for all public classes and methods.
-
 | Class | Description |
 |-------|-------------|
 | [Queue](/python/api-reference/queue) | Central orchestrator — task registration, enqueue, workers, and all queue operations |

docs/content/docs/python/api-reference/queue/events.mdx

@@ -3,8 +3,6 @@ title: Events & Logs
 description: "Event callbacks, webhook delivery, and structured task logging."
 ---
 
-Methods for event callbacks, webhook registration, and structured task logging.
-
 ## Events & webhooks
 
 ### `queue.on_event()`

docs/content/docs/python/api-reference/queue/index.mdx

@@ -5,8 +5,6 @@ description: "The central class for creating and managing a task queue."
 
 import { Callout } from "fumadocs-ui/components/callout";
 
-The central class for creating and managing a task queue.
-
 <Callout type="info" title="Sub-pages">
   The Queue API is split across several pages for readability:
 

docs/content/docs/python/api-reference/queue/jobs.mdx

@@ -3,8 +3,6 @@ title: Job Management
 description: "Methods for retrieving, filtering, cancelling, archiving, and replaying jobs."
 ---
 
-Methods for retrieving, filtering, cancelling, archiving, and replaying jobs.
-
 ## Job retrieval
 
 ### `queue.get_job()`

docs/content/docs/python/getting-started/quickstart.mdx

@@ -5,8 +5,6 @@ description: "Build your first task queue in 5 minutes."
 
 import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 
-Build your first task queue in 5 minutes.
-
 ## 1. Define tasks
 
 Create a file called `tasks.py`:

docs/content/docs/python/guides/advanced-execution/index.mdx

@@ -3,8 +3,6 @@ title: Advanced execution
 description: "Patterns for scaling and optimizing task execution."
 ---
 
-Patterns for scaling and optimizing task execution.
-
 <Cards>
   <Card
     title="Prefork Pool"

docs/content/docs/python/guides/core/index.mdx

@@ -3,8 +3,6 @@ title: Core
 description: "The building blocks of every taskito application."
 ---
 
-The building blocks of every taskito application.
-
 <Cards>
   <Card
     title="Tasks"

docs/content/docs/python/guides/extensibility/index.mdx

@@ -3,8 +3,6 @@ title: Extensibility
 description: "Extend taskito at every stage of the task lifecycle."
 ---
 
-Extend taskito with custom behavior at every stage of the task lifecycle.
-
 <Cards>
   <Card
     title="Middleware"

docs/content/docs/python/guides/observability/index.mdx

@@ -3,8 +3,6 @@ title: Observability
 description: "Monitor, log, and inspect your task queue in real time."
 ---
 
-Monitor, log, and inspect your task queue in real time.
-
 <Cards>
   <Card
     title="Monitoring & Hooks"

docs/content/docs/python/guides/reliability/index.mdx

@@ -3,8 +3,6 @@ title: Reliability
 description: "Harden your task queue for production workloads."
 ---
 
-Harden your task queue for production workloads.
-
 <Cards>
   <Card
     title="Retries & Dead Letters"

docs/content/docs/python/more/examples/index.mdx

@@ -3,8 +3,6 @@ title: Examples
 description: "End-to-end examples demonstrating common taskito patterns."
 ---
 
-End-to-end examples demonstrating common taskito patterns.
-
 | Example | Description |
 |---------|-------------|
 | [FastAPI Service](/python/more/examples/fastapi-service) | REST API that enqueues tasks and streams progress via SSE |