Update documentation structure

README.md

@@ -90,15 +90,15 @@ embedded languages, without requiring a theme or choosing an output format.
 
 | Guide | Contents |
 |---|---|
-| [Documentation index](docs/index.md) | Choose the right guide |
+| [Installation](docs/installation.md) | Requirements, Composer, and verification |
 | [Getting started](docs/getting-started.md) | Complete rendering, line numbers, and errors |
-| [Languages](docs/languages/index.md) | Exact identifiers and language capabilities |
-| [Themes](docs/theming/index.md) | Built-in variants and visual examples |
-| [Create a theme](docs/theming/creating.md) | Implement `ThemeInterface` |
-| [Embedded languages](docs/languages/embedded.md) | HTML, SVG, Markdown, and Twig |
-| [Theme adapters](docs/theming/adapters.md) | Highlight.js, Prism, and TextMate |
-| [Public API](docs/api/index.md) | Parsing, rendering, and extension contracts |
-| [Examples](docs/examples.md) | Compact examples and generated previews |
+| [Examples](docs/examples.md) | Rendered language and theme previews |
+| [Languages](docs/languages.md) | Exact identifiers and language capabilities |
+| [Themes](docs/themes.md) | Built-in variants and visual examples |
+| [Compatibility](docs/compatibility.md) | Exceptions and supported public boundaries |
+
+The [documentation index](docs/index.md) lists these pages in site navigation
+order and links their focused guides.
 
 The complete source examples are available in [`examples/languages/`](examples/languages/).
 
@@ -148,9 +148,9 @@ $light = new GitHubTheme(dark: false);
 $dark = new GitHubTheme();
 ```
 
-Browse the [built-in theme matrix](docs/theming/index.md), learn how to
-[create a theme](docs/theming/creating.md), or reuse an existing stylesheet
-through a [theme adapter](docs/theming/adapters.md).
+Browse the [built-in theme matrix](docs/themes.md), learn how to
+[create a theme](docs/themes/creating.md), or reuse an existing stylesheet
+through a [theme adapter](docs/themes/adapters.md).
 
 ## Integrations
 

docs/compatibility.md

@@ -0,0 +1,37 @@
+# Compatibility
+
+Alto Code Highlight follows semantic versioning for its documented entry
+points and extension contracts. Patch and minor releases preserve their
+signatures and behavior throughout the 1.x series.
+
+## Exceptions
+
+`LanguageNotFoundException` reports an unknown language identifier.
+`ParseException` reports source that a semantic parser cannot process. Both are
+part of the supported exception contract.
+
+Applications may catch those exceptions individually, or catch the package
+exception interface when the same recovery applies to every highlighting
+failure. Keep the original source visible when highlighting is optional.
+
+## Supported boundary
+
+The compatibility promise covers:
+
+- generated element structure and documented CSS classes;
+- source escaping;
+- registered language identifiers;
+- semantic `Scope` values;
+- documented public signatures;
+- the language and theme extension contracts.
+
+The following details are implementation details:
+
+- concrete lexer, parser, state, and token classes inside a built-in language;
+- exact whitespace inside generated HTML;
+- private methods and undocumented types;
+- test fixtures, documentation tooling, and generated showcase assets.
+
+Those details may change in a minor or patch release when documented behavior
+stays compatible. Review the [Languages](languages.md) and
+[Themes](themes.md) pages for the public extension contracts.

docs/examples.md

@@ -6,7 +6,7 @@ parser checks.
 
 Browse the complete source catalog on
 [GitHub](https://github.com/altophp/code-highlight/tree/main/examples/languages),
-or use the individual links in the [language reference](languages/index.md).
+or use the individual links in the [language reference](languages.md).
 
 ## Featured preview matrix
 
@@ -64,5 +64,5 @@ API.
 | ![CSS highlighted with GitHub Dark](assets/examples/github-dark/css.png) | ![CSS highlighted with GitHub Light](assets/examples/github-light/css.png) |
 
 The previews use the same source samples as the package tests. See
-[Creating a theme](theming/creating.md) to use them when reviewing a custom
+[Creating a theme](themes/creating.md) to use them when reviewing a custom
 theme.

docs/getting-started.md

@@ -2,6 +2,9 @@
 
 This guide renders a complete HTML page with one highlighted PHP example.
 
+Save the script below as `highlight.php` beside `vendor`, then run
+`php highlight.php > highlight.html` and open the result in a browser.
+
 ## Render a code block
 
 ```php
@@ -48,6 +51,37 @@ The highlighter escapes source text before it creates HTML. Insert its return
 value as trusted generated markup; escaping that value again would display the
 `<pre>`, `<code>`, and `<span>` tags as text.
 
+The generated page contains a `<pre class="alto-highlight language-php">`
+block and the bundled Alto stylesheet. Compare its rendered colors with the
+checked-in [PHP previews](examples.md#php).
+
+## Parse without rendering
+
+Use `CodeParser` when another component needs semantic tokens instead of HTML:
+
+```php
+use Alto\Code\Highlight\CodeParser;
+
+$stream = (new CodeParser())->parse(
+    '$total = array_sum($prices);',
+    'php',
+);
+
+foreach ($stream as $token) {
+    echo $token->text.' '.$token->scope->value.PHP_EOL;
+}
+```
+
+`parse()` returns a `ParsedStream` and preserves the source exactly:
+`$stream->toString()` equals the original code. The parser also resolves
+configured embedded languages without requiring a theme or choosing an output
+format.
+
+`CodeParser` accepts an optional embedding registry and language list. It also
+exposes `registerLanguage()`, `getEmbeddedRegistry()`, and
+`setEmbeddingEnabled()` for the same parser configuration used by
+`Highlighter`.
+
 ## Construct a highlighter
 
 The concrete constructor accepts a theme and two optional custom registries:
@@ -83,7 +117,7 @@ interface HighlighterInterface
 ```
 
 - `$code` is the source text.
-- `$language` is an exact [registered identifier](languages/index.md).
+- `$language` is an exact [registered identifier](languages.md).
 - `$lineNumbers` adds a numbered span at the start of every line.
 - `$highlightLines` is a list of 1-indexed line numbers. Highlighted numbers
   receive the `alto-highlighted` class.
@@ -169,7 +203,7 @@ Do not emit it for every code block. The same `Highlighter` instance can render
 multiple blocks with the selected theme.
 
 To switch themes, create the requested theme and a corresponding highlighter
-before rendering the page. See the [built-in theme variants](theming/index.md).
+before rendering the page. See the [built-in theme variants](themes.md).
 
 ## Other public operations
 
@@ -179,4 +213,5 @@ before rendering the page. See the [built-in theme variants](theming/index.md).
 - `getEmbeddedRegistry()` to inspect the active embedding plans;
 - `setEmbeddingEnabled()` to toggle a configured host/target pair.
 
-See [Embedded languages](languages/embedded.md) for the embedding contracts.
+See [Embedded languages](languages/embedded.md) for the embedding contracts
+and [Compatibility](compatibility.md) for supported public boundaries.

docs/index.md

@@ -1,54 +1,32 @@
-# Alto Code Highlight documentation
+# Alto Code Highlight
 
-Alto Code Highlight is a server-side syntax highlighter for PHP 8.4 and later.
-It parses source code in PHP and returns escaped, theme-ready HTML. It does not
-require a browser-side highlighter.
-
-## Documentation
-
-- [Installation](installation.md) covers requirements, Composer, and a smoke
-  test.
-- [Getting started](getting-started.md) goes from source code to a complete HTML
-  page.
-- [Examples](examples.md) presents canonical examples and generated visual
-  previews.
-
-## Languages
-
-- [Languages](languages/index.md) lists every accepted language identifier.
-- [Embedded languages](languages/embedded.md) explains HTML, SVG, Markdown, and
-  Twig delegation.
-
-## Theming
-
-- [Themes](theming/index.md) lists all built-in variants and constructors.
-- [Theme adapters](theming/adapters.md) shows how to reuse local Highlight.js,
-  Prism, or TextMate theme files.
-- [Creating a theme](theming/creating.md) implements `ThemeInterface` from
-  semantic scopes to CSS.
-
-## API
-
-- [Public API](api/index.md) defines the supported entry points, extension
-  contracts, and compatibility boundary.
-
-## Public API at a glance
-
-Use `CodeParser` when you need tokens, and `Highlighter` when you need HTML:
+Alto Code Highlight parses source code and renders escaped, theme-ready HTML
+entirely in PHP. Semantic scopes distinguish language concepts across 27
+built-in languages, including embedded CSS, JavaScript, PHP, and markup.
 
 ```php
-use Alto\Code\Highlight\CodeParser;
 use Alto\Code\Highlight\Highlighter;
 use Alto\Code\Highlight\Theme\AltoTheme;
 
-$tokens = (new CodeParser())->parse('$answer = 42;', 'php');
-
 $highlighter = new Highlighter(new AltoTheme());
 $html = $highlighter->highlight('<?php echo "Hello";', 'php');
-$css = $highlighter->getTheme()->getStylesheet();
 ```
 
-The returned HTML is a `<pre class="alto-highlight">` element containing a
-`<code>` element and semantic `<span>` elements. Source text is HTML-escaped
-during rendering. Add the selected theme's stylesheet once to the page, then
-insert the returned HTML without escaping it again.
+The result is escaped semantic HTML ready for the selected theme stylesheet:
+
+```html
+<pre class="alto-highlight language-php"><code class="language-php"><span class="alto-punctuation">&lt;?php </span><span class="alto-keyword">echo</span> <span class="alto-string">&quot;Hello&quot;</span><span class="alto-punctuation">;</span></code></pre>
+```
+
+The package needs no browser-side highlighter, Node.js process, external
+service, or third-party PHP runtime package. It also adapts Highlight.js,
+Prism, and TextMate themes without handing parsing to those tools.
+
+## Documentation
+
+- [Installation](installation.md)
+- [Getting started](getting-started.md)
+- [Examples](examples.md)
+- [Languages](languages.md)
+- [Themes](themes.md)
+- [Compatibility](compatibility.md)

docs/installation.md

@@ -91,7 +91,7 @@ the script that executes it. A framework bootstrap usually already includes
 
 ### A language is reported as unsupported
 
-Use an exact identifier from the [language reference](languages/index.md). The
+Use an exact identifier from the [language reference](languages.md). The
 highlighter normalizes case and surrounding whitespace, but does not provide
 aliases such as `js`, `ts`, `sh`, `yml`, or `cs`.
 

docs/languages/index.md → docs/languages.md

@@ -7,6 +7,9 @@ Identifiers are case-insensitive after trimming, but there are no short
 aliases. Use `javascript`, not `js`; `typescript`, not `ts`; `bash`, not `sh`;
 `yaml`, not `yml`; and `csharp`, not `cs`.
 
+Read [Embedded languages](languages/embedded.md) for HTML, SVG, Markdown, and
+Twig delegation.
+
 ## Default registry
 
 | Language | Identifier | Category | Typical extension | Parsing focus | Example |
@@ -40,7 +43,7 @@ aliases. Use `javascript`, not `js`; `typescript`, not `ts`; `bash`, not `sh`;
 | YAML | `yaml` | Data | `.yaml` | Mappings, sequences, anchors, aliases, values, and comments | [Source](https://github.com/altophp/code-highlight/blob/main/examples/languages/yaml.yaml) |
 
 The source files above are the canonical compact documentation examples.
-See [Examples](../examples.md) for generated previews.
+See [Examples](examples.md) for generated previews.
 
 ## PHP snippets without an opening tag
 
@@ -91,4 +94,16 @@ $highlighter->registerLanguage(new MyLanguage());
 
 Registering an existing identifier replaces that parser on the highlighter
 instance. Theme authors style the generic semantic scopes emitted by parsers;
-see [Creating a theme](../theming/creating.md).
+see [Creating a theme](themes/creating.md).
+
+## Extension contract
+
+Custom parsers implement `LanguageInterface` and return a `ParsedStream` made
+of `ParsedToken` values. `StreamBuilder`, `TokenType`, and `Scope` are
+supported building blocks. `Languages::getDefaultLanguages()` returns the
+built-in registry.
+
+Embedded parsers use `EmbeddedLanguageCapable`, `EmbeddedLanguageContext`, and
+the public types under `Alto\Code\Highlight\Embedded`. Their documented
+constructors and methods follow the same compatibility promise described in
+[Compatibility](compatibility.md).