This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/master by this push:
new d1a4c00044 Add tinker-doc skill for authoring and reviewing
documentation
d1a4c00044 is described below
commit d1a4c00044fe5e3a3685899f8dd9bde02c197189
Author: Stephen Mallette <[email protected]>
AuthorDate: Fri Jun 19 11:53:42 2026 -0400
Add tinker-doc skill for authoring and reviewing documentation
Introduces a standalone tinker-doc Agent Skill covering the craft of
TinkerPop documentation: per-book voice and audience, the house style
rules, executable Gremlin code-block conventions, and AsciiDoc wiring.
Wires it into bin/agent-setup.sh and points tinker-dev's docs note at it.
Assisted-by: Claude Code:claude-opus-4-8
---
.skills/tinker-dev/SKILL.md | 7 +-
.skills/tinker-doc/SKILL.md | 134 +++++++++
.../tinker-doc/references/asciidoc-and-wiring.md | 154 ++++++++++
.skills/tinker-doc/references/books-and-voice.md | 320 +++++++++++++++++++++
.skills/tinker-doc/references/executable-blocks.md | 91 ++++++
bin/agent-setup.sh | 3 +-
6 files changed, 705 insertions(+), 4 deletions(-)
diff --git a/.skills/tinker-dev/SKILL.md b/.skills/tinker-dev/SKILL.md
index 1844425347..08cd67969b 100644
--- a/.skills/tinker-dev/SKILL.md
+++ b/.skills/tinker-dev/SKILL.md
@@ -137,9 +137,10 @@ ones that are easy to miss:
- **Gremlin language tests**: cross-language behavior is tested with Gherkin
features under
`gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features/`
(see `docs/src/dev/developer/for-committers.asciidoc`).
-- **Docs are AsciiDoc** under `docs/src/` — never Markdown in the main docs
tree. Add new
- content to the right book and update its `index.asciidoc`; generate with
`bin/process-docs.sh`
- (Java 11).
+- **Docs are AsciiDoc** under `docs/src/` — never Markdown in the main docs
tree. For writing or
+ revising any documentation (voice, per-book style, executable code blocks,
AsciiDoc wiring),
+ use the **tinker-doc** skill. The mechanical minimum: add new content to the
right book and update
+ its `index.asciidoc`.
- **Changelog**: for user-visible or API changes, update `CHANGELOG.asciidoc`
in the correct
version section. Do not invent version numbers or release names.
diff --git a/.skills/tinker-doc/SKILL.md b/.skills/tinker-doc/SKILL.md
new file mode 100644
index 0000000000..a7046c3439
--- /dev/null
+++ b/.skills/tinker-doc/SKILL.md
@@ -0,0 +1,134 @@
+---
+name: tinker-doc
+description: >
+ Writing, editing and reviewing documentation for the Apache TinkerPop
project. Use
+ when authoring or revising any content under docs/src/ — reference docs,
recipes,
+ tutorials, upgrade/release notes, provider and developer guides — or the
+ CHANGELOG. Covers the TinkerPop documentation voice and the per-book style
+ expectations, the executable Gremlin code-block pipeline, and AsciiDoc
+ conventions. For building and validating code changes, see tinker-dev.
+license: Apache-2.0
+compatibility: Documentation is AsciiDoc under docs/src/, never Markdown.
+metadata:
+ version: 1.0.0
+ project: Apache TinkerPop
+---
+
+# TinkerPop Documentation Skill
+
+This skill is about the **craft** of TinkerPop documentation: getting the
voice,
+audience, and shape of each kind of document right. The mechanics that keep the
+build green (executable code blocks, AsciiDoc wiring) are covered in the
+references and matter, but they serve the writing, not the other way around.
+
+All project documentation lives under `docs/src/` and is **AsciiDoc, never
+Markdown**. It is organized into several books, each with its own audience and
+purpose. The four directories under `docs/src/dev/` are themselves separate
+books, not one:
+
+| Book | Path | Audience | Purpose |
+|---|---|---|---|
+| Reference | `docs/src/reference/` | Users | The complete, authoritative
description of every feature and step |
+| Recipes | `docs/src/recipes/` | Users | Reusable problem→solution patterns
for real tasks |
+| Tutorials | `docs/src/tutorials/` | Users (learning) | Story-driven
walkthroughs of a focused topic |
+| Upgrade | `docs/src/upgrade/` | Users (upgrading) | Announces what changed
in a release and how to adapt |
+| Provider | `docs/src/dev/provider/` | Graph providers | Implementation
guidance, provider policies, and the canonical Gremlin semantics |
+| IO | `docs/src/dev/io/` | Providers and advanced users | The serialization
formats (GraphBinary, GraphSON, GraphML, Gryo) |
+| Developer | `docs/src/dev/developer/` | Contributors | Contributing,
development environment, committer and release process |
+| Future | `docs/src/dev/future/` | Contributors | Design proposals for
planned or possible changes |
+
+The full per-book voice guide, with grounded examples from the real docs, is in
+[references/books-and-voice.md](references/books-and-voice.md). Read it before
+writing in any book you have not written in before. The short version of each
+book's character:
+
+- **Upgrade** announces. It tells a feature's story — what changed and why it
+ matters — and defers exhaustive detail to the reference docs via `See:`
rather
+ than cataloging every edge case itself. A typical entry is short: a
paragraph or
+ two and one example. It frames past shortcomings positively and treats
breaking
+ changes as a priority.
+- **Reference and Recipes** instruct. They are the focal point for correct
+ usage and established patterns: complete, user-friendly, and formal.
+- **Tutorials** teach through a story but otherwise follow the
Reference/Recipes
+ style.
+- **Provider** documents internals in the Reference/Recipes style. The
+ `gremlin-semantics.asciidoc` file is special and load-bearing (see below).
+- **IO** specifies the serialization formats in the same formal, complete style
+ as Provider.
+- **Developer** docs are internal notes, instructions and standard processes
for contributors.
+- **Future** holds design proposals for changes under consideration.
+
+## House style (applies to every book)
+
+These rules hold across all documentation. Existing prose does not always obey
+them; write to the standard, not to the weakest nearby example.
+
+1. **No em-dash or semicolon to break a sentence.** Prefer two separate
+ sentences, or find a transition word that lets the thought flow. (This is a
+ prose rule. Semicolons inside code, such as the `;[]` output-suppression
+ idiom, are unaffected.)
+2. **Formal means no first or second person.** Do not address the reader as
+ "you" or speak as "I" or "we." Write about the subject, not about the author
+ or audience. "The `coalesce()`-step evaluates..." not "You can use
+ `coalesce()` to...".
+3. **Prefer flowing paragraphs over lists.** Use a bulleted or numbered list
+ only when it itemizes something clearly quantifiable, such as the members of
+ an enumeration or a fixed set of options, each needing description. Do not
use
+ a list for open-ended or subjective points (for example, "the benefits of a
+ traversal pattern"). Those belong in prose.
+4. **Avoid hype and marketing language.** Describe what something does and why
it
+ matters in plain, positive terms. Let the capability speak for itself.
+
+## Examples must be real and runnable
+
+TinkerPop documentation is unusual: most Gremlin examples are **executed at
build
+time** against a real graph, and their output is inlined automatically. A block
+marked `[gremlin-groovy,modern]` is run against the modern toy graph and its
+output is filled in for you. Never invent or hand-write the `==>` output of
such
+a block.
+
+The two graphs available to executable blocks are `modern` and `existing`. Use
+a bare `[gremlin-groovy]` block for setup that should run without a graph. When
+an example is purely illustrative and must *not* be executed (a hypothetical,
an
+error case, console session text), use `[source,text]` or `[source,groovy]`
+instead.
+
+**Exception — upgrade documentation is always static.** Every example in
+`docs/src/upgrade/` is a hand-written `[source,groovy]` or `[source,text]`
block,
+**never** an executable `[gremlin-groovy]` block, because an upgrade entry is a
+snapshot of behavior at a fixed point in history (often an old-vs-new
+comparison). This reverses the general rule above: in upgrade docs you **do**
+write the `==>` output by hand. "Static" does not mean "no output" — a static
+upgrade example should still show its results so the reader sees the payoff.
If an
+upgrade example is missing its output, the fix is to write the output in,
**not**
+to convert the block to executable. Do not be talked out of this by the rest of
+the docs being executable, and do not assume the upgrade book contains
executable
+blocks — it does not.
+
+The authoring details — graph choice, output suppression, `<1>` callouts, and
+the multi-language story — are in
+[references/executable-blocks.md](references/executable-blocks.md). AsciiDoc
+structure (anchors, cross-references, the `x.y.z` version placeholder, per-book
+`index.asciidoc` wiring, admonitions, images) is in
+[references/asciidoc-and-wiring.md](references/asciidoc-and-wiring.md).
+
+## The semantics document is load-bearing
+
+`docs/src/dev/provider/gremlin-semantics.asciidoc` is the canonical description
+of Gremlin's semantics. **It must be updated whenever Gremlin steps, the
Gremlin
+grammar (`Gremlin.g4`), or the semantics code change in any way.** When adding
to
+it, follow the patterns already established there for how a concept or step is
+documented rather than inventing a new structure. See
+[references/books-and-voice.md](references/books-and-voice.md#provider-documentation)
+for what those patterns are.
+
+## Don't forget the changelog and upgrade docs
+
+Behavioral and API changes usually need more than reference updates:
+
+- **`CHANGELOG.asciidoc`** (repo root) gets a concise entry in the correct
+ version section. One short clause. Do not invent version numbers or release
+ names.
+- **Upgrade docs** get an entry for user-visible features and especially for
+ breaking changes to public APIs or Gremlin semantics. A breaking change
+ without clear migration guidance in the upgrade docs is incomplete.
diff --git a/.skills/tinker-doc/references/asciidoc-and-wiring.md
b/.skills/tinker-doc/references/asciidoc-and-wiring.md
new file mode 100644
index 0000000000..3d6d9d8183
--- /dev/null
+++ b/.skills/tinker-doc/references/asciidoc-and-wiring.md
@@ -0,0 +1,154 @@
+# AsciiDoc and Wiring
+
+TinkerPop documentation is AsciiDoc, never Markdown. This reference covers the
+structural conventions an agent gets wrong most often. For voice see
+`books-and-voice.md`; for runnable examples see `executable-blocks.md`.
+
+## Anchors and cross-references
+
+Define an anchor on its own line above the heading it names, then link to it
from
+anywhere with `<<anchor,display text>>`:
+
+```
+[[coalesce-step]]
+=== Coalesce Step
+
+... see the <<where-step,where()-step>> for a related filter.
+```
+
+Anchors are how the whole documentation set links together. Give every section
a
+stable, descriptive anchor and prefer cross-referencing an existing section
over
+restating its content.
+
+## The `x.y.z` version placeholder
+
+Links into version-specific resources use the literal placeholder `x.y.z` in
+place of a release number. The build substitutes the real version. This applies
+to javadoc links, links into the published site, and GitHub source links:
+
+```
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#gremlin-console[Gremlin
Console]
+link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/.../GraphTraversal.html#coalesce(...)++[`coalesce(Traversal...)`]
+```
+
+Never hard-code a concrete version like `3.7.6` in these links. The `++...++`
+double-plus wrapping is used to escape URLs that contain characters AsciiDoc
would
+otherwise interpret (such as the parentheses in a javadoc method signature).
+
+**Exception: upgrade documentation.** Links from the upgrade docs to other
+versioned documentation are deliberately pinned to a concrete version (for
+example `.../docs/3.7.4/reference/...`), not `x.y.z` and not `current`,
because an
+upgrade entry is a snapshot in time. This exception applies *only* to the
upgrade
+book. See
+[books-and-voice.md](books-and-voice.md#upgrade-documentation) for the full
+reasoning.
+
+If you need actually use `x.y.z` as a literal value, prefer `xx.yy.zz`.
+
+## Additional References blocks
+
+Reference step sections end with a pointer block under a bold label. It always
+carries the javadoc link, and when the step has an entry in the Gremlin
Semantics
+documentation it also links there with the link text `` `Semantics` ``:
+
+```
+*Additional References*
+
+link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/.../GraphTraversal.html#conjoin(java.lang.String)++[`conjoin(String)`]
+link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#conjoin-step++[`Semantics`]
+```
+
+The semantics link points to `dev/provider/#<step>-step` (the anchor in
+`gremlin-semantics.asciidoc`), uses the `x.y.z` placeholder, and is wrapped in
+`++...++`. Whenever a step's behavior is specified in the semantics document,
+include this link so the reference and the specification stay connected. Match
+this format when adding a new step so the reference stays uniform.
+
+## See blocks (upgrade documentation)
+
+Upgrade documentation has its own closing convention. An upgrade entry ends
with a
+`See:` line that points the reader to the sources where the change can be
explored
+in more depth. Where reference sections use `*Additional References*`, upgrade
+entries use `See:`.
+
+A single pointer:
+
+```
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-3225[TINKERPOP-3225]
+```
+
+Several pointers are comma-separated, each `link:` on its own line, all under
one
+`See:`:
+
+```
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-2672[TINKERPOP-2672],
+link:https://tinkerpop.apache.org/docs/3.7.1/reference/#asString-step[asString()-step],
+link:https://tinkerpop.apache.org/docs/3.7.1/reference/#length-step[length()-step]
+```
+
+Conventions observed in the upgrade docs:
+
+- **JIRA issues** are the most common target. The link text is the bare ticket
+ id, `TINKERPOP-XXXX`, linking to
`https://issues.apache.org/jira/browse/TINKERPOP-XXXX`.
+- **Reference (and other doc) links** are version-pinned, not `x.y.z` (see the
+ upgrade exception above), with descriptive link text such as
+ `Reference Documentation - Metrics` or the step name `trim()-step`.
+- **Mailing-list threads** point to `https://lists.apache.org/thread/...` with
+ link text naming the thread, often beginning `[DISCUSS]`.
+- **Proposals** link to the proposal file on GitHub, for example
+
`https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-scoping-5.asciidoc`,
+ with a descriptive title as the link text.
+
+Use `See:` with the colon. A scattering of older entries omit it; the colon is
the
+standard.
+
+## Book wiring: `index.asciidoc`
+
+Each book has an `index.asciidoc` that sets document attributes and pulls in
its
+content files with `include::` directives, in reading order:
+
+```
+:docinfo: shared
+:toc-position: left
+
+include::the-graph.asciidoc[]
+include::the-traversal.asciidoc[]
+```
+
+A **new content file is invisible until it is included.** After creating a
file,
+add an `include::` for it to that book's `index.asciidoc` at the correct
position.
+Forgetting this is the most common reason new documentation does not appear.
+
+## Admonitions
+
+AsciiDoc admonitions call out information without breaking into a list. The
four
+in regular use, in rough order of frequency, are `NOTE:`, `IMPORTANT:`,
`WARNING:`,
+and `TIP:`. Use them for genuine asides and cautions, not as a substitute for
+well-structured prose:
+
+```
+IMPORTANT: This tutorial assumes the Gremlin Console is installed.
+```
+
+## Images
+
+Images are referenced with `image::file.png[width=500]` for block images and
+`image:file.png[width=130]` (single colon) for inline ones. Image files live
+under `docs/static/images/`. Set a sensible `width`, and `align="center"` where
+the surrounding content does.
+
+## Quick checklist for a new or changed doc
+
+The list below is a fixed, enumerable set of mechanical steps, which is exactly
+the case where a list is appropriate:
+
+1. Right book, right file, AsciiDoc not Markdown.
+2. Stable `[[anchor]]` on every new section.
+3. Executable examples use `[gremlin-groovy,modern]` (or `existing`); no
+ hand-written `==>` output. Non-executed examples use `[source,text]`.
+4. Version-specific links use the `x.y.z` placeholder.
+5. New files added to the book's `index.asciidoc` via `include::`.
+6. Semantics, grammar, or step changes reflected in
+ `gremlin-semantics.asciidoc`.
+7. User-visible or breaking changes reflected in `CHANGELOG.asciidoc` and the
+ upgrade docs.
diff --git a/.skills/tinker-doc/references/books-and-voice.md
b/.skills/tinker-doc/references/books-and-voice.md
new file mode 100644
index 0000000000..eb0d338275
--- /dev/null
+++ b/.skills/tinker-doc/references/books-and-voice.md
@@ -0,0 +1,320 @@
+# Books and Voice
+
+Each book in `docs/src/` serves a different reader at a different moment.
Getting
+a document right starts with knowing which book it belongs to and writing in
that
+book's voice. The house-style rules in `SKILL.md` (no em-dash or
sentence-breaking
+semicolon, formal third person, paragraphs over lists, no hype) apply
throughout.
+The guidance below is what is specific to each book.
+
+---
+
+## Upgrade Documentation
+
+`docs/src/upgrade/` — one file per minor line (`release-3.7.x.asciidoc`, etc.),
+newest release section at the top, split into "Upgrading for Users" and, where
+relevant, provider-facing notes.
+
+Upgrade documentation **announces** a release. It is the place where a feature
is
+introduced to the world. This shapes everything about how it reads.
+
+**It is not a coding reference; it tells a story.** An upgrade entry gives the
+reader a clear, engaging account of what a feature is and why it matters, then
+lets them follow the `See:` references for the full detail when they want it.
The
+goal is to make the feature interesting and understood, not to specify it.
State
+the point of the change and show one good example, then stop.
+
+**Do not catalog every corner of the feature.** This is the most common way an
+upgrade entry goes wrong. Resist enumerating every overload, every argument
+variation, and every runtime behavior (what happens with zero, with a partial
+result, when nothing remains, and so on). That exhaustive cataloging is
precisely
+what the reference and semantics docs are for, and the `See:` link sends the
+reader there. A well-chosen example already demonstrates the important
behaviors,
+so a prose paragraph that narrates each case after it is usually redundant and
+should be cut.
+
+A typical upgrade entry is short: a heading, a paragraph or two on what changed
+and why it matters, one example, and the `See:` line. The clearest warning
sign is
+a paragraph after the example that walks through edge cases such as an empty
+result, a zero argument, or an exhausted iterator. That reads as specification
+rather than story, and it is what the reference docs behind the `See:` link are
+for. The test for any sentence is whether it conveys why the feature is useful
or
+merely specifies how it behaves. The latter belongs in the reference docs.
+
+**Announce without hype.** The tone is positive and informative, never
+marketing. Avoid "powerful," "blazing fast," "game-changing," and similar.
+Describe the capability plainly and let it be interesting on its own terms.
+
+**Frame past shortcomings positively.** When a release fixes a bug or removes a
+limitation, describe it as an improvement to how TinkerPop works now, not as a
+confession of how broken it used to be. State what the old behavior was
factually,
+then what the new behavior is, without self-criticism.
+
+**Lead major changes with history.** When a release changes how TinkerPop does
+something fundamental, breaks with tradition, or alters a public API, open the
+section with a short account of how the project arrived here. That context is
what
+makes a disruptive change feel reasoned rather than arbitrary. This history is
+often more nuanced than the changeset reveals, so do not try to reconstruct it
by
+searching the internet or inferring it from the diff. If the history is not
+already at hand, ask the human for it.
+
+**Compare old and new syntax in examples.** The most useful upgrade example
shows
+the before and the after side by side. The established pattern uses comment
+labels inside a single block:
+
+```
+[source,groovy]
+----
+// 3.7.6
+gremlin> g.inject([null]).conjoin("-")
+==>null
+
+// 3.7.7
+gremlin> g.inject([null]).conjoin("+")
+==>
+----
+```
+
+**Upgrade examples must always be static blocks.** Use `[source,groovy]` or
+`[source,text]`, never an executable `[gremlin-groovy]` block. An upgrade
example
+is a snapshot of behavior at a specific moment in the project's history, often
+contrasting two versions at once. It must not be regenerated against the
current
+build, which would erase the very before-and-after the example exists to show.
+
+Static does not mean output-free. A static upgrade example should still include
+its results, written in by hand, so the reader sees the payoff of the change:
+
+```
+[source,groovy]
+----
+gremlin> g.V().has('age', gt(__.V(1).values('age'))).values('name')
+==>josh
+==>peter
+----
+```
+
+When reviewing upgrade docs, a query example shown without its expected results
+is a real gap, but the fix is to **add the hand-written `==>` output**, never
to
+convert the block to executable. Converting it would defeat the snapshot
purpose
+and is always the wrong call in this book.
+
+**Examples should be impactful, not exhaustive or contrived.** Choose a use
case
+that catches attention and makes the value obvious. One well-chosen, realistic
+example beats five that exercise every option.
+
+**Breaking changes are the priority.** Breaking changes to public APIs and to
+Gremlin semantics are the most important thing upgrade documentation does. For
+each one, state clearly what breaks, why, and exactly how a user minimizes the
+impact (what to change in their code, what to check for). A breaking change
+documented without a migration path is incomplete.
+
+**Close an entry with a `See:` block.** Most upgrade entries end with a `See:`
+line that sends the reader to where the change can be explored further: the
JIRA
+issue, the relevant reference documentation, a `[DISCUSS]` mailing-list
thread, a
+design proposal, or several of these together. The JIRA issue is the most
common
+and uses the bare ticket id as its link text (`See:
+link:...[TINKERPOP-XXXX]`). The full format, including how multiple targets are
+listed, is in
+[asciidoc-and-wiring.md](asciidoc-and-wiring.md#see-blocks-upgrade-documentation).
+
+**Pin cross-reference links to a concrete version.** This is the one place
where
+the usual `x.y.z` placeholder rule does *not* apply. Because an upgrade entry
is a
+snapshot tied to a specific release, a link out to the reference docs (or any
+other versioned documentation) must name the actual version it refers to, not
+`x.y.z` and not `current`:
+
+```
+See: link:https://tinkerpop.apache.org/docs/3.7.4/reference/#metrics[Reference
Documentation - Metrics]
+```
+
+A `current` or `x.y.z` link would drift as new releases ship and eventually
point
+the reader at documentation that no longer matches the change being described.
+This pinning is peculiar to upgrade documentation. Everywhere else, use the
+`x.y.z` placeholder as normal.
+
+---
+
+## Reference Documentation
+
+`docs/src/reference/` — the authoritative, complete description of TinkerPop.
+`the-traversal.asciidoc` documents the steps; other files cover variants,
+applications, and implementations.
+
+Reference documentation **instructs**. Where upgrade docs introduced a feature,
+reference docs are the focal point for its proper, ongoing use. The style is
+**user-friendly, complete, informative, and formal**.
+
+The established shape of a step section:
+
+```
+[[coalesce-step]]
+=== Coalesce Step
+
+The `coalesce()`-step evaluates the provided traversals in order and returns
the
+first traversal that emits at least one element.
+
+[gremlin-groovy,modern]
+----
+g.V(1).coalesce(outE('knows'),
outE('created')).inV().path().by('name').by(label)
+----
+
+*Additional References*
+
+link:++https://tinkerpop.apache.org/javadocs/x.y.z/.../GraphTraversal.html#coalesce(...)++[`coalesce(Traversal...)`]
+```
+
+Conventions to follow:
+
+- A dedicated anchor (`[[coalesce-step]]`) and a `=== Title Case Step` heading.
+- An opening sentence that defines the step in third person, naming it as
+ `` `coalesce()`-step `` and, where the docs do so for its neighbors, tagging
+ its category in bold (for example `*filter*` or `*map*`).
+- One or more **executable** `[gremlin-groovy,modern]` examples that
demonstrate
+ real behavior on the toy graph.
+- An `*Additional References*` block linking to the javadoc, and, when the step
+ has an entry in the Gremlin Semantics documentation, a `` `Semantics` ``
link to
+ `dev/provider/#<step>-step`. Both use the `x.y.z` version placeholder (see
+ `asciidoc-and-wiring.md`).
+
+Completeness matters here in a way it does not in the upgrade docs. The
reference
+is where a user goes to learn how a step actually behaves in all its normal
uses.
+
+---
+
+## Recipes Documentation
+
+`docs/src/recipes/` — one file per pattern.
+
+Recipes share Reference's voice (user-friendly, complete, informative, formal)
+but are organized around a **task** rather than a feature. A recipe states a
+problem a user genuinely has, then builds the traversal that solves it,
+explaining the reasoning as it goes.
+
+The signature recipe device is the **numbered callout**, which attaches prose
+explanation to specific lines without breaking the flow of the example:
+
+```
+[gremlin-groovy,modern]
+----
+g.V(1).bothE() <1>
+g.V(1).bothE().where(otherV().hasId(2)) <2>
+----
+
+<1> There are three edges from the vertex with the identifier of "1".
+<2> Filter those three edges using the `where()`-step ...
+```
+
+Recipes often layer from a simple case to progressively richer ones, which
suits
+the "build up a solution" framing. Keep the prose between examples flowing and
+formal.
+
+---
+
+## Tutorials
+
+`docs/src/tutorials/` — `getting-started`, `the-gremlin-console`,
+`gremlins-anatomy`, `gremlin-language-variants`, each in its own directory.
+
+Tutorials are **story-driven** and cover one focused topic, taking a reader
from
+unfamiliar to capable. Beyond that narrative arc, they follow the
+Reference/Recipes style: complete, informative, and formal. Tutorials make
heavy
+use of `link:` cross-references out to the published site (with the `x.y.z`
+placeholder) to connect the story to the reference material, and they open with
+`:docinfo: shared` directives and a logo image.
+
+Note that some existing tutorial prose slips into second person ("inspire you
to
+new levels"). That is legacy phrasing, not the standard. New and revised
tutorial
+content should stay in formal third person like the rest of the documentation.
+
+---
+
+## Provider Documentation
+
+`docs/src/dev/provider/` — for graph providers implementing TinkerPop, and to
+some extent for advanced users. The voice matches Reference and Recipes:
+informative, complete, formal.
+
+### The semantics document
+
+`gremlin-semantics.asciidoc` is the canonical specification of how Gremlin
+behaves: equality, comparability, orderability, equivalence, type promotion,
and
+the semantics of each construct. **It must be updated whenever Gremlin steps,
the
+grammar (`Gremlin.g4`), or the semantics code change in any way.** Treat it as
+part of the change, not an afterthought.
+
+The document has two parts. The conceptual sections near the top (equality,
+comparability, orderability, equivalence, type promotion) specify the
+cross-cutting behaviors and change rarely. The large `== Steps` section
documents
+each Gremlin step individually, and that is where most edits land: per-step
+coverage is still incomplete, and new steps, changed semantics, and new
overloads
+all show up here. Expect to spend your time in `== Steps`, not in the equality
and
+comparability material.
+
+When adding or revising a step, **follow the per-step template already in
use.**
+Each step is anchored as `[[<step>-step]]` under a `=== stepName()` heading and
+fills in the same labeled fields, in order:
+
+- `*Description:*` — one or two sentences on what the step does.
+- `*Syntax:*` — each overload as a backticked signature, multiple overloads
+ separated by `|` (for example `` `asString()` | `asString(Scope scope)` ``).
+- A `[width="100%",options="header"]` table with the columns
+ `Start Step | Mid Step | Modulated | Domain | Range`.
+- `*Arguments:*` — one bullet per argument. (A genuine enumeration, so a list
is
+ the right choice here.)
+- `*Modulation:*` — present only for steps that take modulators such as
+ `from()`/`to()`.
+- `*Considerations:*` — prose covering edge cases, grammar restrictions, and
any
+ GLV-specific notes.
+- `*Exceptions*` — the conditions under which the step throws.
+- A closing `See:` line linking to the step's source file(s) and its reference
+ entry, using the `x.y.z` placeholder.
+
+A new overload usually means adding its signature to `*Syntax:*` and describing
+the new argument under `*Arguments:*`. A semantic change usually means revising
+`*Considerations:*` or `*Exceptions*`. Match a nearby existing step rather than
+inventing a new structure, and fill the gap when documenting a step that has no
+entry yet.
+
+Examples in the semantics document are illustrative, not executed. They use
+`[source,text]` blocks showing the `gremlin>` prompt, because the point is to
+specify behavior precisely rather than to run it against a toy graph.
+
+---
+
+## Developer Documentation
+
+`docs/src/dev/developer/` — internal notes for contributors (contributing,
+development environment, for-committers, release, administration).
+
+This is in-project material written for people working on TinkerPop itself. The
+formal house style still applies. There is little beyond that to special-case:
+keep it accurate, keep it current with the actual process, and match the
+structure of the surrounding committer documentation.
+
+---
+
+## IO Documentation
+
+`docs/src/dev/io/` — one file per serialization format (`graphbinary.asciidoc`,
+`graphson.asciidoc`, `graphml.asciidoc`, `gryo.asciidoc`).
+
+IO documentation specifies the wire and file formats that providers and
advanced
+users implement against. It carries the same formal, complete, precise voice as
+Provider documentation. Accuracy is paramount: this is a specification, so type
+mappings, byte layouts, and format versions must match the implementation
+exactly. Match the structure already used for the format being edited rather
than
+reorganizing it, and keep examples illustrative (`[source,text]` or
+`[source,json]`) rather than executable.
+
+---
+
+## Future Documentation
+
+`docs/src/dev/future/` — numbered design proposals (`proposal-*.asciidoc`) for
+changes under consideration.
+
+Future documentation captures proposed and planned work, so it reads
differently
+from the rest. A proposal argues for a direction: it lays out motivation, the
+proposed design, alternatives, and open questions. The formal house style still
+applies, but the content is forward-looking and provisional rather than a
+description of how TinkerPop behaves today. When adding a proposal, follow the
+numbering and structure of the existing `proposal-*` files.
diff --git a/.skills/tinker-doc/references/executable-blocks.md
b/.skills/tinker-doc/references/executable-blocks.md
new file mode 100644
index 0000000000..92e91e31f9
--- /dev/null
+++ b/.skills/tinker-doc/references/executable-blocks.md
@@ -0,0 +1,91 @@
+# Executable Code Blocks
+
+The defining feature of TinkerPop documentation is that most Gremlin examples
are
+**executed when the docs are built**. Each executable block is fed to a live
+Gremlin Console, run against a real graph, and its actual `==>` output is
inlined
+automatically. This is what keeps the documentation honest, and it has a direct
+consequence for how examples are written: the author supplies the Gremlin,
never
+the output.
+
+## Block types
+
+| Block opener | Executed? | Use for
|
+|---|---|--------------------------------------------------------------------------------------------------------------|
+| `[gremlin-groovy,modern]` | Yes, against the **modern** toy graph | The
default for most examples
|
+| `[gremlin-groovy,existing]` | Yes, against the **existing** graph | Examples
that build on or mutate graph state from the immediately previous block
|
+| `[gremlin-groovy]` | Yes, with **no** graph bound | Setup that does not need
a graph
|
+| `[source,groovy]` | No | Illustrative Groovy that must not run
(hypotheticals, two-version comparisons); **all upgrade-doc examples** |
+| `[source,text]` | No | Console sessions, error cases, or specification
examples shown verbatim |
+
+Only `modern` and `existing` are available as graph names. The **modern** graph
+is the standard six-element toy graph used almost everywhere. Reach for
`existing`
+only when an example genuinely needs to persist or mutate state that a later
block
+depends on.
+
+### Never invent output
+
+For any **executed** block, write only the Gremlin lines. Do **not** type the
+`==>` result lines yourself. They are filled in automatically. Hand-written
output
+in an executable block is wrong by definition and will be overwritten or will
+conflict with reality.
+
+Conversely, in a non-executed `[source,text]` or `[source,groovy]` block you
+write the whole thing, prompts and output included, because nothing runs it.
This
+is how upgrade docs show before/after behavior and how the semantics document
+specifies results.
+
+### Upgrade documentation always uses static blocks
+
+Upgrade documentation must **never** use an executable `[gremlin-groovy]`
block.
+Every example in the upgrade docs is a static `[source,groovy]` or
`[source,text]`
+block whose output is written by hand. An upgrade example is a snapshot of how
+something behaved at a particular point in the project's history, frequently
+showing an old version next to a new one. Regenerating it against the current
+build would defeat its purpose, so these examples are deliberately kept static.
+
+## Output suppression: the `;[]` idiom
+
+When a line in an executable block is setup whose output would be noise (a
+variable assignment, a schema-building call), append `;[]` to it. The statement
+still executes, but it returns an empty list, so no `==>` line is emitted:
+
+```
+[gremlin-groovy,modern]
+----
+v1 = g.V(1).next();[]
+v2 = g.V(2).next();[]
+g.V(v1).bothE().where(otherV().is(v2))
+----
+```
+
+Here the two assignments run silently and only the final traversal produces
+visible output.
+
+## Numbered callouts
+
+To explain specific lines without interrupting the example, use AsciiDoc
+callouts. Mark lines with `<1>`, `<2>`, and so on, then list the explanations
+immediately after the block:
+
+```
+[gremlin-groovy,modern]
+----
+g.V(1).bothE() <1>
+g.V(1).bothE().where(otherV().hasId(2)) <2>
+----
+
+<1> There are three edges from the vertex with the identifier of "1".
+<2> Filter those edges with `where()` ...
+```
+
+Align the callout markers into a column for readability, as the existing
recipes
+do. This is the primary explanatory device in the recipes book.
+
+## The multi-language story
+
+The reference examples are written in Gremlin-Groovy. When documenting a step,
+write the Groovy example. Do not hand-maintain parallel copies in every
language
+inside a step section unless the surrounding content already does so. The
+dedicated per-language material (connecting, imports, configuration) lives in
+`reference/gremlin-variants.asciidoc`, organized under `[[gremlin-python]]`,
+`[[gremlin-javascript]]`, and similar anchors.
diff --git a/bin/agent-setup.sh b/bin/agent-setup.sh
index 33b19d57cd..4b817ec585 100755
--- a/bin/agent-setup.sh
+++ b/bin/agent-setup.sh
@@ -22,6 +22,7 @@
#
# TinkerPop maintains Agent Skills in .skills/:
# tinker-dev - Development guidance (coding conventions, build recipes,
etc.)
+# tinker-doc - Documentation authoring and review (voice, per-book style,
etc.)
# tinker-review - Graph-based PR review (knowledge graph analysis,
playbooks, etc.)
#
# Different AI coding tools discover skills in different directories. This
script
@@ -47,7 +48,7 @@
set -uo pipefail
-SKILLS=("tinker-dev" "tinker-review")
+SKILLS=("tinker-dev" "tinker-doc" "tinker-review")
RED='\033[0;31m'
GREEN='\033[0;32m'
