diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 73b3fd3..aac78f4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,19 +9,32 @@ python -m venv ~/.venvs/zensical
 source ~/.venvs/zensical/bin/activate
 pip install zensical
 ```
-### Preview site locally
-Once installed, activate the venv and run Zensical from the repository root:
+### Running Zensical
+
+Once installed, either activate the venv or run the binary directly:
 
 ```bash
+# Option 1: Activate the venv
 source ~/.venvs/zensical/bin/activate
-
-# Live preview with hot-reload
 zensical serve
 
-# Production build
-zensical build --clean
+# Option 2: Run directly without activating
+~/.venvs/zensical/bin/zensical serve
 ```
 
+Common commands:
+
+- `zensical serve` — live preview with hot-reload
+- `zensical build --clean` — production build
+- Review build output for broken link warnings
+
+### Adding New Pages
+
+1. Create the markdown file in `docs/`
+2. Add the page to the nav section in `zensical.toml`
+3. Create corresponding code examples in all three languages under `examples/`
+4. Test locally with `zensical serve`
+
 ## Vendored dependencies
 
 The Zensical theme lazy-loads a few third-party assets (Mermaid for diagrams,
diff --git a/README.md b/README.md
index 551c432..42e749a 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,7 @@
-# AWS Lambda durable functions developer documentation source
+# AWS Lambda durable execution developer documentation source
 
 This repository contains the source for the AWS Lambda Durable Execution SDK
-documentation website at https://docs.aws.amazon.com/durable-execution,
-providing comprehensive guides and references for building resilient,
+documentation website at https://docs.aws.amazon.com/durable-execution, providing comprehensive guides and references for building resilient,
 long-running applications with AWS Lambda durable functions across
 multiple programming languages.
 
@@ -40,10 +39,9 @@ pip install zensical
 zensical serve
 ```
 
-For the full authoring workflow — adding code samples, formatting conventions,
-commit messages, and pull request process — see
-[CONTRIBUTING.md](CONTRIBUTING.md). For Markdown formatting syntax, please see
-the [Authoring Guide](authoring-guide.md).
+For the full authoring workflow, please see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+For writing style and Markdown formatting syntax, please see the [Authoring Guide](authoring-guide.md).
 
 ## Kiro Power
 
@@ -64,6 +62,7 @@ for details.
 - [AWS Lambda durable functions Documentation](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html)
 - [JavaScript SDK Repository](https://github.com/aws/aws-durable-execution-sdk-js)
 - [Python SDK Repository](https://github.com/aws/aws-durable-execution-sdk-python)
+- [Java SDK Repository](https://github.com/aws/aws-durable-execution-sdk-java)
 
 ## Feedback & Support
 
diff --git a/authoring-guide.md b/authoring-guide.md
index 200221c..c28758c 100644
--- a/authoring-guide.md
+++ b/authoring-guide.md
@@ -1,257 +1,426 @@
+# Authoring Guide
 
-# Getting started
+This guide covers how to author documentation for AWS Lambda Durable Functions.
+For setup and contribution workflow, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-For full documentation visit [zensical.org](https://zensical.org/docs/).
+Each SDK reference page must be equally useful to TypeScript, Python, and Java
+developers. No language is the implicit default. Language-specific quirks
+belong inside the relevant tab, not in shared prose.
 
-## Commands
-* [`zensical serve`][serve] - Start local web server
-* [`zensical build`][build] - Build your site
+## Verify Against SDK Source
 
-  [serve]: https://zensical.org/docs/usage/preview/
-  [build]: https://zensical.org/docs/usage/build/
+Before writing or updating any copy or examples, read the actual SDK source
+for every language. Do not trust existing docs. Do not guess. Verify every
+argument name, type, and return type against the source.
 
-## Example formatting
+Verify means: check each argument, each type of each argument and return,
+find the definition for each of those types, and if those types reference
+sub-types, find those too. Recurse until you have the full picture.
 
-### Admonitions
+For each code example:
 
-> Go to [documentation](https://zensical.org/docs/authoring/admonitions/)
+1. Find the method definition in the SDK source, not tests or docs
+2. For each parameter, find its type definition. Recurse through nested types.
+3. For Java, check both the sync and async variants (e.g. `step()` and `stepAsync()`)
+4. Check the testing libraries of each repo for examples to verify your example code actually works
 
-!!! note
+### SDK repositories
 
-    This is a **note** admonition. Use it to provide helpful information.
+You will need the SDK source for all three languages. Clone them alongside
+the docs repo:
 
-!!! warning
+| Repository | Source path to read |
+|---|---|
+| [aws-durable-execution-sdk-js](https://github.com/aws/aws-durable-execution-sdk-js) | `packages/aws-durable-execution-sdk-js/src` |
+| [aws-durable-execution-sdk-python](https://github.com/aws/aws-durable-execution-sdk-python) | `src/aws_durable_execution_sdk_python` |
+| [aws-durable-execution-sdk-java](https://github.com/aws/aws-durable-execution-sdk-java) | `sdk/src/main/java/software/amazon/lambda/durable` |
 
-    This is a **warning** admonition. Be careful!
+Testing SDKs are useful for confirming example code compiles and runs. The
+JavaScript and Java testing SDKs live in the same repos as the main SDKs
+(under `-testing` package paths). The Python testing SDK lives in a separate
+repo:
 
-### Details
+| Repository | Source path to read |
+|---|---|
+| [aws-durable-execution-sdk-python-testing](https://github.com/aws/aws-durable-execution-sdk-python-testing) | `src/aws_durable_execution_sdk_python_testing` |
 
-> Go to [documentation](https://zensical.org/docs/authoring/admonitions/#collapsible-blocks)
 
-??? info "Click to expand for more info"
-    
-    This content is hidden until you click to expand it.
-    Great for FAQs or long explanations.
+### Key source files
 
-## Code Blocks
+- **TypeScript**: `types/durable-context.ts` for `DurableContext`. Check
+  `types/step.ts`, `types/core.ts`, etc. for referenced types.
+- **Python**: `context.py` for `DurableContext`. Check `config.py` for
+  `StepConfig` and `StepSemantics`. Check `types.py` for `StepContext`.
+- **Java**: `DurableContext.java` for the interface. Check
+  `config/StepConfig.java`, `StepContext.java`, `StepSemantics.java`.
 
-> Go to [documentation](https://zensical.org/docs/authoring/code-blocks/)
+## Writing Style
 
-``` python hl_lines="2" title="Code blocks"
-def greet(name):
-    print(f"Hello, {name}!") # (1)!
+### Voice and Tone
+
+Write for developers who want to learn how to use the SDK. Be direct and
+technical. Avoid marketing language ("powerful", "flexible", "seamless").
+
+Don't use unnecessary words. Keep sentences concise.
+
+Use active voice. Write "the SDK checkpoints the result" not "the result is
+checkpointed".
+
+Every sentence must earn its place. If a sentence restates what the code
+already shows, delete it.
+
+Per Strunk and White, use definite, specific, concrete language. Prefer
+the specific to the general, the definite to the vague, the concrete to
+the abstract. In practice, avoid 'to be' and 'to have' where you can use
+stronger verbs.
+
+### Sentence Structure
+
+Do not use emdash (—) or hyphen as a dash. If you feel tempted to use one,
+break it into two sentences or use a comma.
+
+Keep sentences short. One idea per sentence.
 
-greet("Python")
+### What to Avoid
+
+**Listicles.** Do not create Terminology, Key Features, Best Practices, or
+FAQ sections. These are convenient for LLMs but not for humans learning to
+code. If you feel tempted to write one, fold the content into prose:
+
+- New terms: introduce the term naturally in the prose where it first appears
+- "Key features": drop them (usually marketing), or fold the underlying
+  capability into the relevant section
+- Best practices: fold the guidance into the section where it applies. A
+  naming best practice belongs in the "Naming steps" section, not a generic
+  "Best Practices" list.
+- FAQ Q&As: each question is either (a) a concept that belongs in prose,
+  (b) a code example that belongs in a code section, or (c) something
+  already covered elsewhere that doesn't need repeating
+
+**Navigation artifacts.** Do not add Table of Contents, "Back to top" links,
+or "Back to X" links. Zensical generates navigation automatically.
+
+**Language-specific notes outside tabs.** Any note that applies to only one
+language belongs inside that language's tab, not in shared prose.
+
+### List Items
+
+Do not use emdash or hyphen to separate a list item heading from its
+description. Use bold or links instead:
+
+```markdown
+- **StepConfig** configures retry behavior and timeouts
+- [wait()](operations/wait.md) pauses execution for a duration
 ```
 
-1.  > Go to [documentation](https://zensical.org/docs/authoring/code-blocks/#code-annotations)
+## Revise, Don't Append
 
-    Code annotations allow to attach notes to lines of code.
+When you update a page, revise the whole section. A fresh reader should not
+have to reconcile an opening sentence with a later correction tacked on at
+the end.
 
-Code can also be highlighted inline: `#!python print("Hello, Python!")`.
+If your new content qualifies, corrects, or extends something earlier on the
+page, rewrite the earlier prose too. Don't leave stale sentences in place
+because they were there first.
 
-## Content tabs
+Signs you are appending instead of revising:
 
-> Go to [documentation](https://zensical.org/docs/authoring/content-tabs/)
+- A new sentence at the end of a paragraph that qualifies an earlier one
+- A "Note" or "Update" near the end of a section that contradicts the opening
+- Two adjacent paragraphs making overlapping points
+- A new code example below an older, now-redundant one
 
-=== "Python"
+When you spot one in your own edit, rewrite the section so the reader gets
+a single, coherent story.
+
+## Look Before You Write
+
+Before writing a new page or section, search the docs for the topic. If
+another page already covers it, add to that page instead of creating a
+parallel explanation. Readers should get one canonical answer, not two
+competing ones.
+
+If you find conflicting information on another page, fix both at once. Don't
+leave a contradiction for the next reader to sort out.
+
+This applies equally to new pages and to edits on existing pages. A new
+section on an existing page can duplicate content elsewhere just as easily
+as a whole new page can.
 
-    ``` python
-    print("Hello from Python!")
+## Language Neutrality
+
+Tab order is always: **TypeScript → Python → Java**.
+
+If a language has a quirk, note it inside that language's tab:
+
+```markdown
+=== "TypeScript"
+
+    Pass `undefined` as the name to omit it.
+
+    ```typescript
+    --8<-- "examples/typescript/operations/steps/basic-step.ts"
     ```
 
-=== "Rust"
+=== "Python"
+
+    The `@durable_step` decorator uses the function name automatically.
 
-    ``` rs
-    println!("Hello from Rust!");
+    ```python
+    --8<-- "examples/python/operations/steps/basic-step.py"
     ```
 
-## Diagrams
+=== "Java"
 
-> Go to [documentation](https://zensical.org/docs/authoring/diagrams/)
+    The name is always required. Pass `null` to omit it.
 
-``` mermaid
-graph LR
-  A[Start] --> B{Error?};
-  B -->|Yes| C[Hmm...];
-  C --> D[Debug];
-  D --> B;
-  B ---->|No| E[Yay!];
+    ```java
+    --8<-- "examples/java/operations/steps/basic-step.java"
+    ```
 ```
 
-## Footnotes
+## Page Structure
 
-> Go to [documentation](https://zensical.org/docs/authoring/footnotes/)
+SDK reference pages follow this pattern:
 
-Here's a sentence with a footnote.[^1]
+1. One or two short paragraphs explaining what the operation does and when
+   to use it
+2. A minimal walkthrough example (tabs, all three languages)
+3. Method signature section with per-language tabs
+4. Parameters listed after the tabs (shared where identical, inside tabs
+   where language-specific)
+5. Returns and Throws/Raises after parameters
+6. Sub-sections for config types (StepConfig, StepContext, SemanticsEnum)
+   each with per-language tabs
+7. Conceptual sub-sections as needed (naming, configuration, data passing,
+   nesting, concurrency)
+8. "See also" at the end
 
-Hover it, to see a tooltip.
+### Exemplar pages
 
-[^1]: This is the footnote.
+Model tone and structure on these pages:
 
+- [`wait.md`](docs/sdk-reference/operations/wait.md): simple method
+- [`step.md`](docs/sdk-reference/operations/step.md): complex method with multiple types
+- [`wait-for-condition.md`](docs/sdk-reference/operations/wait-for-condition.md): complex method with multiple types
 
-## Formatting
+### Template
 
-> Go to [documentation](https://zensical.org/docs/authoring/formatting/)
+```markdown
+# {Operation Name}
 
-- ==This was marked (highlight)==
-- ^^This was inserted (underline)^^
-- ~~This was deleted (strikethrough)~~
-- H~2~O
-- A^T^A
-- ++ctrl+alt+del++
+## {Concept heading — what it does}
 
-## Icons, Emojis
+{One or two paragraphs. Language-neutral. No listicles.}
 
-> Go to [documentation](https://zensical.org/docs/authoring/icons-emojis/)
+{Simple walkthrough example with tabs}
 
-* :sparkles: `:sparkles:`
-* :rocket: `:rocket:`
-* :tada: `:tada:`
-* :memo: `:memo:`
-* :eyes: `:eyes:`
+## Method signature
 
-## Maths
+### {method name}
 
-> Go to [documentation](https://zensical.org/docs/authoring/math/)
+=== "TypeScript"
+    {signature}
+    **Parameters:**
+    - ...
+    **Returns:** ...
+    **Throws:** ...
 
-$$
-\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
-$$
+=== "Python"
+    {signature}
+    **Parameters:**
+    - ...
+    **Returns:** ...
+    **Raises:** ...
 
-!!! warning "Needs configuration"
-    Note that MathJax is included via a `script` tag on this page and is not
-    configured in the generated default configuration to avoid including it
-    in a pages that do not need it. See the documentation for details on how
-    to configure it on all your pages if they are more Maths-heavy than these
-    simple starter pages.
+=== "Java"
+    {sync and async signatures}
+    **Parameters:**
+    - ...
+    **Returns:** ...
+    **Throws:** ...
 
-<script id="MathJax-script" async src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>
-<script>
-  window.MathJax = {
-    tex: {
-      inlineMath: [["\\(", "\\)"]],
-      displayMath: [["\\[", "\\]"]],
-      processEscapes: true,
-      processEnvironments: true
-    },
-    options: {
-      ignoreHtmlClass: ".*|",
-      processHtmlClass: "arithmatex"
-    }
-  };
-</script>
+### {ConfigType}
 
-## Task Lists
+{same pattern — interface/dataclass/builder per tab}
 
-> Go to [documentation](https://zensical.org/docs/authoring/lists/#using-task-lists)
+### {ContextType}
 
-* [x] Install Zensical
-* [x] Configure `zensical.toml`
-* [x] Write amazing documentation
-* [ ] Deploy anywhere
+### {SemanticsEnum}
 
-## Tooltips
+## The {operation}'s function
 
-> Go to [documentation](https://zensical.org/docs/authoring/tooltips/)
+### Anonymous {operation} functions
 
-[Hover me][example]
+### Pass arguments to the {operation} function
 
-  [example]: https://example.com "I'm a tooltip!"
+## Naming {operations}
 
+## Configuration
 
-# basic markdown guide
-# Markdown in 5min
+## See also
 
-## Headers
-```
-# H1 Header
-## H2 Header
-### H3 Header
-#### H4 Header
-##### H5 Header
-###### H6 Header
+- [Related page](link)
 ```
 
-## Text formatting
-```
-**bold text**
-*italic text*
-***bold and italic***
-~~strikethrough~~
-`inline code`
-```
+## Code Examples
+
+### Requirements
+
+All code examples must:
+
+- Include all three languages (TypeScript, Python, Java)
+- Be functionally equivalent across languages
+- Include necessary imports
+- Be minimal. Show the concept, not a full application.
+- Avoid comments that restate what the code does
+- Be verified against the actual SDK source before committing
+
+### File Organization
 
-## Links and images
 ```
-[Link text](https://example.com)
-[Link with title](https://example.com "Hover title")
-![Alt text](image.jpg)
-![Image with title](image.jpg "Image title")
+examples/
+  typescript/{section}/{subsection}/{example-name}.ts
+  python/{section}/{subsection}/{example-name}.py
+  java/{section}/{subsection}/{example-name}.java
 ```
 
-## Lists
+Use hyphens in filenames. All three languages must have the same set of files.
+
+### Embedding in Docs
+
+Use the `--8<--` snippet syntax with content tabs:
+
+```markdown
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/operations/steps/basic-step.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/operations/steps/basic-step.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/operations/steps/basic-step.java"
+    ```
 ```
-Unordered:
-- Item 1
-- Item 2
-  - Nested item
-
-Ordered:
-1. First item
-2. Second item
-3. Third item
+
+### Method Signatures
+
+Show the actual callable signature, not pseudocode. Use real types from the
+SDK.
+
+For Java, show both sync and async variants:
+
+```markdown
+=== "Java"
+
+    ```java
+    // sync
+    <T> T step(String name, Class<T> resultType, Function<StepContext, T> func)
+    <T> T step(String name, Class<T> resultType, Function<StepContext, T> func, StepConfig config)
+
+    // async
+    <T> DurableFuture<T> stepAsync(String name, Class<T> resultType, Function<StepContext, T> func)
+    <T> DurableFuture<T> stepAsync(String name, Class<T> resultType, Function<StepContext, T> func, StepConfig config)
+    ```
 ```
 
-## Blockquotes
+For TypeScript, show both overloads if they exist (e.g. named and unnamed).
+
+## Formatting Reference
+
+This project uses [Zensical](https://zensical.org) to build the documentation
+site.
+
+### Admonitions
+
+```markdown
+!!! note
+
+    This is a note admonition.
+
+!!! warning
+
+    This is a warning admonition.
 ```
-> This is a blockquote
-> Multiple lines
->> Nested quote
+
+### Collapsible Blocks
+
+```markdown
+??? info "Click to expand"
+
+    Hidden content here.
 ```
 
-## Code blocks
-````
-```javascript
-function hello() {
-  console.log("Hello, world!");
-}
+### Code Blocks
+
+````markdown
+```python hl_lines="2" title="Example"
+def greet(name):
+    print(f"Hello, {name}!")
 ```
 ````
 
-## Tables
-```
-| Header 1 | Header 2 | Header 3 |
-|----------|----------|----------|
-| Row 1    | Data     | Data     |
-| Row 2    | Data     | Data     |
-```
+Inline code with syntax highlighting: `` `#!python print("Hello")` ``
 
-## Horizontal rule
-```
----
-or
-***
-or
-___
-```
+### Content Tabs
 
-## Task lists
-```
-- [x] Completed task
-- [ ] Incomplete task
-- [ ] Another task
-```
+```markdown
+=== "TypeScript"
 
-## Escaping characters
-```
-Use backslash to escape: \* \_ \# \`
+    ```typescript
+    console.log("Hello");
+    ```
+
+=== "Python"
+
+    ```python
+    print("Hello")
+    ```
 ```
 
-## Line breaks
+### Diagrams
+
+````markdown
+```mermaid
+graph LR
+  A[Start] --> B{Error?};
+  B -->|Yes| C[Retry];
+  B -->|No| D[Done];
 ```
-End a line with two spaces  
-to create a line break.
+````
 
-Or use a blank line for a new paragraph.
+### Tables
+
+```markdown
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| name | string | Step identifier |
+| config | StepConfig | Optional configuration |
 ```
+
+## Checklist Before Committing
+
+- [ ] All prose is language-neutral (no Python-only concepts described as universal)
+- [ ] No Table of Contents, no "Back to top" links, no "Back to X" links
+- [ ] No Terminology, Key Features, Best Practices, or FAQ sections
+- [ ] Tab order is TypeScript → Python → Java everywhere
+- [ ] Language-specific notes are inside tabs, not outside
+- [ ] All three languages have example files for every `--8<--` reference
+- [ ] Every example verified against the actual SDK source
+- [ ] Java method signatures show both sync and async variants
+- [ ] TypeScript signatures show both overloads where they exist
+- [ ] No emdash, no hyphen-as-dash
+- [ ] No passive voice
+- [ ] Updates are revisions, not tacked-on additions
+- [ ] Topic is not already covered (or duplicated) on another page
+- [ ] No contradictions with other pages
+- [ ] Ran `~/.venvs/zensical/bin/mdformat docs/path/to/file.md` on the updated file
+- [ ] Previewed with `~/.venvs/zensical/bin/zensical serve`