Skip to content

Commit b1581b0

Browse files
os-zhuangclaude
os-zhuang
and
claude
authored
docs(content): one h1 per docs page — 137 deletions, 16 demotions, and a gate (#12262)
* docs(content): drop the duplicate body H1 from 153 hand-written pages DocsTitle renders the frontmatter title as the page h1, so a body-level '# ' heading makes the page ship a second one. 137 pages repeated the title verbatim (heading deleted); 16 said something different (demoted to '## ', which keeps the wording and keeps the slug). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(scripts): add check:docs-single-h1 so a body h1 cannot come back Fences are stripped before anything looks for a heading: a naive scan reports 205 files, ten of which are shell comments inside working examples. The frontmatter and heading-text models are imported from check-doc-anchors rather than retyped, so the gate cannot disagree with the renderer about what a heading says. Two subtrees are excluded with named owners, and an exclusion whose tree is clean is a FAILURE, so the carve-outs retire themselves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
1 parent 8cdd696 commit b1581b0

156 files changed

Lines changed: 480 additions & 290 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/lint.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1071,6 +1071,32 @@ jobs:
10711071
- name: Docs anchors resolve to real headings
10721072
run: pnpm check:doc-anchors
10731073

1074+
# #12236 one <h1> per doc page. `DocsTitle` renders the frontmatter `title`
1075+
# as the page's <h1> unconditionally (apps/docs/app/[lang]/docs/[[...slug]]/
1076+
# page.tsx), so a body-level `# ` heading compiles to a SECOND one inside
1077+
# `DocsBody`. Measured on the dev server at /docs/data-modeling/objects
1078+
# before the sweep: two <h1>, both reading "Object Metadata". 195 of the 403
1079+
# pages were in that state, 138 of them with the two <h1> identical.
1080+
#
1081+
# It lives next to check:doc-anchors because the two share the corpus and
1082+
# the heading model — this gate imports `stripFrontmatter` and
1083+
# `flattenHeadingText` from that one rather than re-modelling either, which
1084+
# is what makes the delete-vs-demote remedy right on the nine pages whose
1085+
# two headings differ only by inline code markup.
1086+
#
1087+
# The gate strips FENCED CODE before looking for a heading, and that is the
1088+
# load-bearing half: a naive `^# ` scan reports 205 files, ten of which are
1089+
# shell/YAML comments inside working examples. A fence-blind rule does not
1090+
# over-report by ten, it instructs the fixer to corrupt ten snippets.
1091+
#
1092+
# Two subtrees are excluded, each with a named owner (#12249 generated
1093+
# reference pages, #12250 release notes) and each self-retiring: the gate
1094+
# FAILS with DEAD-EXCLUSION when an excluded tree becomes clean, so the
1095+
# carve-outs cannot outlive their reasons. A run that judges zero pages
1096+
# fails too (#4690).
1097+
- name: One `<h1>` per docs page
1098+
run: pnpm check:docs-single-h1
1099+
10741100
# #9014 docs redirects: `apps/docs/redirects.mjs` is a 92-entry table of
10751101
# PERMANENT (308) redirects, and before this step nothing in the repo read
10761102
# it — `dispatch-gates.mjs apps/docs/redirects.mjs` named no family over 99

‎content/docs/ai/actions-as-tools.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ title: Actions as Tools
33
description: Expose declarative Action metadata as AI-callable tools with explicit opt-in, HITL approval, and permission-aware execution
44
---
55

6-
# Actions as Tools
7-
86
Part of the [AI module](/docs/ai) — how existing Action metadata becomes LLM-callable, and the guardrails around it.
97

108
This is what makes the app you built **AI-operable**: connect an MCP client (Claude Code, Cursor, …) and your business Actions become callable tools — so an agent can "resolve this ticket" or "convert this lead" through the same logic and permissions as the Console button.

‎content/docs/ai/agents.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ title: AI Agents
33
description: The two platform agents (ask and build), how skills extend them, and the shape of an AgentSchema record
44
---
55

6-
# AI Agents
7-
86
Part of the [AI module](/docs/ai). In the **open edition**, agents, tools, and
97
skills are **typed metadata**. You author **skills** (`defineSkill`) — agents are
108
platform-owned and tool records are optional (see below) — from the open

‎content/docs/ai/connect-mcp.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ title: Connect an MCP Client
33
description: Point Claude Code, Claude Desktop, or any MCP client at your running app — OAuth or API key — and verify the agent can see and operate it.
44
---
55

6-
# Connect an MCP Client
7-
86
Every ObjectStack deployment is already an MCP server. The runtime serves the
97
[Model Context Protocol](https://modelcontextprotocol.io) at **`/api/v1/mcp`**
108
— on by default, no plugin to install, no configuration step. Your objects and

‎content/docs/ai/index.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ title: AI Overview
33
description: Complete guide to leveraging AI agents, RAG pipelines, and intelligent automation in ObjectStack
44
---
55

6-
# AI Overview
7-
86
AI in ObjectStack is a **cross-protocol capability layer**: agents, tools, and knowledge retrieval sit on top of the same objects, actions, permissions, and automation that power the rest of the platform. This module covers the architecture and each of its moving parts.
97

108
<Callout type="info">

‎content/docs/ai/knowledge-rag.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ title: Knowledge & RAG
33
description: The Knowledge Protocol — permission-aware RAG for agents via pluggable adapter plugins (memory, RAGFlow, custom)
44
---
55

6-
# Knowledge & RAG
7-
86
Part of the [AI module](/docs/ai) — how agents retrieve knowledge through the Knowledge Protocol and its adapter plugins.
97

108
ObjectStack ships a Knowledge Protocol that lets you retrieve from pluggable backends (RAGFlow, LlamaIndex, Dify, custom pgvector, …) with one call: `KnowledgeService.search(query, { sourceIds?, topK? })`. The framework defines the contract and runs permission-aware filtering; the adapter plugin does the actual retrieval. See [the protocol design](/docs/protocol/knowledge) for the rationale.

‎content/docs/ai/natural-language-queries.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ title: Natural Language Queries
33
description: How agents query live data through the open MCP data tools (query_records, get_record, aggregate_records) under RLS
44
---
55

6-
# Natural Language Queries
7-
86
Part of the [AI module](/docs/ai) — how natural-language questions become ObjectQL queries at runtime.
97

108
Natural-language querying is **open**. Point your own AI — Claude, Cursor, any

‎content/docs/ai/skills-reference.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ title: AI Skills Reference
33
description: Reference for every ObjectStack AI skill — domain-scoped knowledge modules that teach AI assistants the protocol's schemas and constraints
44
---
55

6-
# AI Skills Reference
7-
86
ObjectStack ships a set of **domain-specific skills** that teach AI assistants (Claude Code, GitHub Copilot, Cursor, …) the protocol's schemas, patterns, and constraints — plus **process** skills that teach how work moves through a project rather than what to author. This guide is the complete catalog.
97

108
<Callout type="info">

‎content/docs/ai/skills.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,6 @@ description: How ObjectStack uses structured AI skills to enable intelligent cod
55

66
import { Bot, Brain, Cpu, Database, Globe, Layout, Shield, Workflow, Wrench, Languages, Zap, Puzzle, BookOpen, Target, ArrowRight } from 'lucide-react';
77

8-
# AI Skills System
9-
108
ObjectStack introduces a **Skills System** — structured, domain-specific knowledge modules that enable AI assistants (GitHub Copilot, Claude Code, Cursor, etc.) to understand and generate protocol-compliant code. Skills are what make [building with Claude Code](/docs/getting-started/build-with-claude-code) reliable: they teach the agent the protocol's rules up front, so it authors correct metadata instead of guessing.
119

1210
<Callout type="info">

‎content/docs/ai/tools.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ title: Tool Records
33
description: The three ways a capability reaches an agent, and the narrow case where authoring a tool record is the right answer
44
---
55

6-
# Tool Records
7-
86
Part of the [AI module](/docs/ai). `tool` is an authorable metadata kind —
97
`ToolSchema`, declared as `defineStack({ tools })` — and it is the **least
108
likely** answer to "how do I give my agent a new capability".

0 commit comments

Comments
 (0)