docs: add Syntax component for inline language-specific identifiers

.agents/references/mdx-authoring.md

@@ -22,6 +22,21 @@ Practical reference for writing documentation in this repo. This site uses Astro
 </Tabs>
 ```
 
+`<Syntax>` is also globally available. Use it when shared prose needs to reference a language-specific identifier — any method name, parameter, class name, or short expression that differs between Python and TypeScript:
+
+```mdx
+Use <Syntax py=".as_tool()" ts=".asTool()" /> to customize the tool name.
+The <Syntax py="Agent.retry_strategy" ts="Agent.retryStrategy" /> parameter controls retry behavior.
+```
+
+Renders as inline `<code>` by default. Pass `plain` for plain text. Reacts live to the global language toggle — no page reload.
+
+**When to use `<Syntax>` vs `<Tabs>`:**
+- `<Syntax>`: single identifier or short expression that differs by language, embedded in a prose sentence.
+- `<Tabs>`: code blocks, multi-line examples, or content that's structurally different between languages.
+
+Never spell out both language variants manually in prose. Use `<Syntax>` instead.
+
 For other Starlight components (`Aside`, `Card`, `CardGrid`, `LinkCard`, `Icon`, `Badge`), use explicit imports:
 
 ```mdx

.agents/references/voice-guide.md

@@ -322,7 +322,7 @@ Strands ships both a Python and TypeScript SDK. Most doc pages show code in both
 - Python has `from strands import Agent`, TypeScript has `import { Agent } from '@strands-agents/sdk'` (verify current package name)
 - Error handling differs: Python raises exceptions, TypeScript may use different patterns
 
-**Prose between tabs should be language-neutral.** Don't write "Pass the `retry_strategy` parameter..." when the tabs show both Python and TypeScript. Write "Configure a retry strategy:" and let the code speak for itself. Language-specific parameter names belong in the code blocks, not in the prose.
+**Prose between tabs should be language-neutral — or use `<Syntax>`.** When shared prose needs to reference a language-specific identifier, use the `<Syntax>` component rather than spelling out both variants manually. This adapts to the reader's language selection and keeps prose clean. For introductory sentences before tabs, you can also write language-neutral prose ("Configure a retry strategy:") and let the code speak for itself.
 
 **Never name the language inside its own tab.** The reader selected the tab; they know which language they're reading. State facts directly without prefixing the language name. The tab itself provides that context.
 

.agents/skills/docs-audit/SKILL.md

@@ -59,6 +59,7 @@ Specific checks:
 - Is essential context at the top?
 - Is inline code properly formatted with backticks?
 - Is terminology consistent with the terminology lock?
+- Are language-specific identifiers in shared prose using the `<Syntax>` component rather than being spelled out manually with language labels?
 
 ### Step 5: Competitive comparison (optional)
 

.agents/skills/docs-reviewer/SKILL.md

@@ -27,7 +27,7 @@ Reference `../../references/voice-guide.md` for the full layer definitions. Chec
 - **Narrative flow:** Start with why the topic matters and what use-case problems it solves. Throughout, show how to implement using Strands SDK in a self-contained, concise way.
 - **Framing:** Does the first sentence of every section describe the developer's goal? Flag sections leading with API descriptions.
 - **Register:** Is the tone appropriate for the content type?
-- **Constraints:** Scan for banned phrases, em-dashes, passive voice, hedging. Apply type-aware overrides (passive in reference is fine; longer sentences in explanation are fine). Flag any prose inside a `<Tab>` that names the language of that tab (e.g., "Python requires..." inside the Python tab, "In TypeScript..." inside the TypeScript tab). The reader chose the tab; they know what language they're reading.
+- **Constraints:** Scan for banned phrases, em-dashes, passive voice, hedging. Apply type-aware overrides (passive in reference is fine; longer sentences in explanation are fine). Flag any prose inside a `<Tab>` that names the language of that tab (e.g., "Python requires..." inside the Python tab, "In TypeScript..." inside the TypeScript tab). The reader chose the tab; they know what language they're reading. Flag language-specific identifiers spelled out manually in shared prose — these should use the `<Syntax>` component to adapt to the reader's language selection.
 - **Authenticity:** Structural variety, visible editorial choices, concision.
 
 ### 2. Terminology Consistency

.agents/skills/docs-writer/SKILL.md

@@ -52,7 +52,9 @@ Write each section following the outline.
 
 ### Step 3b: Apply MDX formatting
 
-Apply MDX formatting patterns from `../../references/mdx-authoring.md` — especially Tabs/Tab syntax, snippet includes, and callout syntax.
+Apply MDX formatting patterns from `../../references/mdx-authoring.md` — especially Tabs/Tab syntax, the `<Syntax>` component for inline language-specific identifiers, snippet includes, and callout syntax.
+
+When shared prose needs to reference a language-specific identifier (method name, parameter, class, etc.), use `<Syntax py="..." ts="..." />`. This keeps prose clean and adapts to the reader's language selection. Never spell out both variants manually in prose.
 
 Code examples longer than a few lines live in runnable `.ts`/`.py` source files alongside the MDX page, not inline. Pull them in via the `--8<--` include syntax. See "Snippet Inclusion" and "TypeScript Snippet Scoping" in `mdx-authoring.md` for the imports/body file pattern and naming conventions.
 

site/CONTRIBUTING.md

@@ -28,6 +28,7 @@ npm run build      # generates static site
 - Content lives in `docs/` as standard Markdown files
 - Navigation structure is defined in `src/config/navigation.yml`
 - Use `<Tabs>` / `<Tab label="...">` for Python/TypeScript code tabs (auto-imported)
+- Use `<Syntax py="python_name" ts="tsName" />` for inline language-specific identifiers in prose (auto-imported). Renders as `<code>` by default; pass `plain` for plain text. Reacts live to the global language toggle.
 - Use `--8<-- "path/to/file.ts:snippet_name"` to pull in code snippets from external files
 - Relative file links (e.g. `../tools/index.md`) resolve automatically — no need to use slugs
 - Link to API reference pages with the `@api` shorthand: `[@api/python/strands.agent.agent](#Class)`

site/SITE-ARCHITECTURE.md

@@ -246,7 +246,7 @@ Available: `Tabs`/`TabItem`, `Aside`, `Card`/`CardGrid`, `LinkCard`, `Icon`, `Ba
 
 ### Auto-Imported Components
 
-We use [astro-auto-import](https://github.com/delucis/astro-auto-import) to make `Tabs` and `Tab` available globally without explicit imports. Since language tabs appear on nearly every page, this reduces boilerplate.
+We use [astro-auto-import](https://github.com/delucis/astro-auto-import) to make `Tabs`, `Tab`, and `Syntax` available globally without explicit imports. Since language tabs and inline language-specific identifiers appear on nearly every page, this reduces boilerplate.
 
 ```mdx
 <!-- No import needed — just use directly -->
@@ -266,6 +266,25 @@ For other components, use [explicit imports](https://starlight.astro.build/compo
 
 A wrapper around Starlight's `Tabs` that auto-generates a `syncKey` from tab labels. Tabs with identical label sets automatically sync together across the page. Auto-imported as `Tabs` (see above).
 
+### `Syntax`
+
+Inline component for language-specific identifiers in prose. Renders the Python or TypeScript variant based on the global language toggle, avoiding the `"python_name (Python) or tsName (TypeScript)"` pattern. Auto-imported.
+
+```mdx
+Pass <Syntax py="context_manager" ts="contextManager" /> to configure...
+```
+
+Props:
+- `py` (required): Python syntax variant
+- `ts` (required): TypeScript syntax variant
+- `plain` (default: `false`): Renders as plain text instead of `<code>`.
+
+The component reads the same `localStorage` key as the language toggle and swaps live without page reload.
+
+**When to use:** Any time a single identifier, method name, or parameter differs between Python and TypeScript and you're writing shared prose (not inside a `<Tab>` section).
+
+**When NOT to use:** For code blocks (use `<Tabs>`), for conceptual differences between SDKs that aren't simple name swaps, or for content that only applies to one language.
+
 ### `PageLink`
 
 Replaces the default anchor element to enable MkDocs-style relative linking. Resolves relative hrefs against the current page's path and validates against the content collection. Logs warnings in development for broken links. Auto-imported as the default `a` element.

site/astro.config.mjs

@@ -101,6 +101,9 @@ export default defineConfig({
           ],
           './src/components/AutoSyncTabs.astro': [
             ['default', "Tabs"]
+          ],
+          './src/components/Syntax.astro': [
+            ['default', 'Syntax']
           ]
         },
       ],

site/src/components/Syntax.astro

@@ -0,0 +1,69 @@
+---
+interface Props {
+  py: string;
+  ts: string;
+  plain?: boolean;
+}
+
+const { py, ts, plain = false } = Astro.props;
+---
+
+<syntax-switch>
+  {plain ? (
+    <>
+      <span data-lang="Python">{py}</span>
+      <span data-lang="TypeScript">{ts}</span>
+    </>
+  ) : (
+    <>
+      <code data-lang="Python">{py}</code>
+      <code data-lang="TypeScript">{ts}</code>
+    </>
+  )}
+</syntax-switch>
+
+<style>
+  /* Default: show TypeScript, hide Python (matches site-wide default) */
+  syntax-switch [data-lang="Python"] {
+    display: none;
+  }
+</style>
+
+<script is:inline>
+  (function () {
+    if (window.__strandsSyntaxSwitchInit) return;
+    window.__strandsSyntaxSwitchInit = true;
+
+    var STORAGE_KEY = 'starlight-synced-tabs__jarkqt';
+    var DEFAULT_LANG = 'TypeScript';
+
+    function getLang() {
+      try { return localStorage.getItem(STORAGE_KEY) || DEFAULT_LANG; }
+      catch (e) { return DEFAULT_LANG; }
+    }
+
+    function updateAll() {
+      var lang = getLang();
+      document.querySelectorAll('syntax-switch [data-lang]').forEach(function (el) {
+        el.style.display = el.getAttribute('data-lang') === lang ? 'inline' : 'none';
+      });
+    }
+
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', updateAll);
+    } else {
+      updateAll();
+    }
+
+    window.addEventListener('storage', function (e) {
+      if (e.key === STORAGE_KEY) updateAll();
+    });
+
+    document.addEventListener('click', function (e) {
+      var btn = e.target && e.target.closest && e.target.closest('.lang-option');
+      if (btn) {
+        Promise.resolve().then(updateAll);
+      }
+    });
+  })();
+</script>

site/src/content/docs/contribute/contributing/documentation.mdx

@@ -6,6 +6,27 @@ sidebar:
 
 Good documentation helps developers succeed with Strands. We welcome contributions that make our docs clearer, more complete, or more helpful. Our documentation lives in the `site/` directory of the [Strands SDK repository](https://github.com/strands-agents/harness-sdk).
 
+## Agent skills
+
+The repository ships agent skills in `.agents/skills/` that encode our documentation conventions, site components, and quality standards. If you're using an AI coding assistant, activate these skills before making documentation changes — they'll produce output that matches our style without you needing to internalize everything on this page.
+
+| Skill | What it does |
+|-------|--------------|
+| `docs-writer` | Drafts or rewrites documentation pages following site conventions |
+| `docs-reviewer` | Reviews drafts for voice, structure, and terminology before PR |
+| `docs-audit` | Assesses a page for quality, accuracy, and voice compliance |
+| `docs-planner` | Identifies documentation gaps and prioritizes the backlog |
+
+Use them by giving your agent a goal that references the skill:
+
+```
+Write a new doc page for the retry strategies feature. Use the docs-writer skill.
+```
+
+```
+Audit the context management page for accuracy and voice issues. Use the docs-audit skill.
+```
+
 ## What we accept
 
 We're looking for contributions that improve the developer experience. Documentation changes can range from small typo fixes to complete new guides.
@@ -115,3 +136,4 @@ agent("What's the weather like?")
 </Tab>
 </Tabs>
 
+

site/src/content/docs/user-guide/concepts/agents/agent-loop.mdx

@@ -87,9 +87,9 @@ Each model invocation ends with a stop reason that determines what happens next:
 - **End turn**: The model has finished its response and has no further actions to take. This is the normal successful termination. The loop exits and returns the model's final message.
 - **Tool use**: The model wants to execute one or more tools before continuing. The loop executes the requested tools, appends the results to the conversation history, and invokes the model again.
 - **Cancelled**: The agent was stopped externally via `agent.cancel()`. See [Cancellation](#cancellation) below.
-- **Limit turns** (`limit_turns` / `limitTurns`): The per-invocation turn budget was exhausted. See [Invocation Limits](#invocation-limits).
-- **Limit total tokens** (`limit_total_tokens` / `limitTotalTokens`): The cumulative token budget was exhausted. See [Invocation Limits](#invocation-limits).
-- **Limit output tokens** (`limit_output_tokens` / `limitOutputTokens`): The output token budget was exhausted. See [Invocation Limits](#invocation-limits).
+- **Limit turns** (<Syntax py="limit_turns" ts="limitTurns" />): The per-invocation turn budget was exhausted. See [Invocation Limits](#invocation-limits).
+- **Limit total tokens** (<Syntax py="limit_total_tokens" ts="limitTotalTokens" />): The cumulative token budget was exhausted. See [Invocation Limits](#invocation-limits).
+- **Limit output tokens** (<Syntax py="limit_output_tokens" ts="limitOutputTokens" />): The output token budget was exhausted. See [Invocation Limits](#invocation-limits).
 - **Max tokens**: The model's response was truncated because it hit the token limit. This is unrecoverable within the current loop. The model cannot continue from a partial response, and the loop terminates with an error.
 - **Stop sequence**: The model encountered a configured stop sequence. Like end turn, this terminates the loop normally.
 - **Content filtered**: The response was blocked by safety mechanisms.

site/src/content/docs/user-guide/concepts/agents/conversation-management.mdx

@@ -100,7 +100,7 @@ Key features of the `SlidingWindowConversationManager`:
 - **Maintains Window Size**: Automatically removes messages from the window if the number of messages exceeds the limit.
 - **Dangling Message Cleanup**: Removes incomplete message sequences to maintain valid conversation state.
 - **Overflow Trimming**: In the case of a context window overflow, it will trim the oldest messages from history until the request fits in the models context window.
-- **Configurable Tool Result Truncation**: Enable or disable truncation of tool results when the message exceeds context window limits. When enabled (the default; `should_truncate_results=True` in Python, `shouldTruncateResults: true` in TypeScript), the oldest message with tool results is truncated first so recent context is preserved as long as possible. Truncation depends on content type:
+- **Configurable Tool Result Truncation**: Enable or disable truncation of tool results when the message exceeds context window limits. When enabled (the default; <Syntax py="should_truncate_results=True" ts="shouldTruncateResults: true" />), the oldest message with tool results is truncated first so recent context is preserved as long as possible. Truncation depends on content type:
     - Text payloads keep their head and tail, separated by a `<truncated chars="N"/>` marker.
     - Images, videos, binary documents, and oversized JSON are replaced by a typed placeholder, for example `[image: png, source: bytes, 12345 bytes]`.
     - The tool result's original `status` and `error` fields are preserved.

site/src/content/docs/user-guide/concepts/agents/hooks.mdx

@@ -28,7 +28,7 @@ Hook callbacks are registered against specific event types and receive strongly-
 
 ### Registering Individual Hook Callbacks
 
-The simplest way to register a hook callback is using the `agent.add_hook()` method:
+The simplest way to register a hook callback is using the <Syntax py="agent.add_hook()" ts="agent.addHook()" /> method:
 
 <Tabs>
 <Tab label="Python">

site/src/content/docs/user-guide/concepts/agents/prompts.mdx

@@ -110,7 +110,7 @@ result = agent.tool.current_time(timezone="US/Pacific")
 </Tab>
 </Tabs>
 
-Direct tool calls bypass the natural language interface and execute the tool using specified parameters. These calls are added to the conversation history by default. However, you can opt out of this behavior by setting `record_direct_tool_call=False` in Python.
+Direct tool calls bypass the natural language interface and execute the tool using specified parameters. These calls are added to the conversation history by default. However, you can opt out of this behavior by setting <Syntax py="record_direct_tool_call=False" ts="recordDirectToolCall: false" />.
 
 ## Prompt Engineering
 

site/src/content/docs/user-guide/concepts/agents/retry-strategies.mdx

@@ -3,7 +3,7 @@ title: Retry Strategies
 tags: [event-loop, error-handling]
 ---
 
-Model providers occasionally encounter errors such as rate limits, service unavailability, or network timeouts. By default, the agent retries throttled responses automatically with exponential backoff. The `Agent.retry_strategy` (Python) or `Agent.retryStrategy` (TypeScript) parameter lets you customize this behavior.
+Model providers occasionally encounter errors such as rate limits, service unavailability, or network timeouts. By default, the agent retries throttled responses automatically with exponential backoff. The <Syntax py="Agent.retry_strategy" ts="Agent.retryStrategy" /> parameter lets you customize this behavior.
 
 ## Default Behavior
 
@@ -129,7 +129,7 @@ agent = Agent(
 
 ## When Retries Occur
 
-Default retry strategies handle throttling errors (`ModelThrottledException` in Python, `ModelThrottledError` in TypeScript) raised by model providers for rate-limiting. Other exceptions propagate immediately without retry.
+Default retry strategies handle throttling errors (<Syntax py="ModelThrottledException" ts="ModelThrottledError" />) raised by model providers for rate-limiting. Other exceptions propagate immediately without retry.
 
 To extend or narrow the retryable set, see [Custom Retry Logic](#custom-retry-logic).
 

site/src/content/docs/user-guide/concepts/agents/snapshots.mdx

@@ -144,7 +144,7 @@ snapshot = agent.take_snapshot(preset="session", exclude=["interrupt_state"])
 
 ## Application Data
 
-Snapshots support an `app_data` (Python) / `appData` (TypeScript) field for storing application-owned data alongside the agent state. Strands does not read or modify this data — it's passed through verbatim.
+Snapshots support an <Syntax py="app_data" ts="appData" /> field for storing application-owned data alongside the agent state. Strands does not read or modify this data — it's passed through verbatim.
 
 This is useful for attaching metadata like a display name for the snapshot, the current step in a workflow, user preferences, or any other context your application needs to associate with a particular point in time.
 

site/src/content/docs/user-guide/concepts/agents/state.mdx

@@ -318,7 +318,7 @@ print(result.state)
 </Tab>
 </Tabs>
 
-Invocation state (`invocationState` in TypeScript, `invocation_state` / `request_state` in Python):
+Invocation state (<Syntax py="invocation_state" ts="invocationState" />):
 
 - Is initialized at the beginning of each agent invocation (defaults to `{}` when omitted)
 - Persists through recursive event loop cycles within a single invocation