Update documentation structure

README.md

@@ -1,4 +1,4 @@
-# ALTO CodeKit
+# ALTO Code Kit
 
 Compose source slicing and semantic highlighting into immutable annotated code snippets.
 
@@ -8,7 +8,7 @@ Compose source slicing and semantic highlighting into immutable annotated code s
   ![License](https://img.shields.io/github/license/altophp/code-kit?label=License&labelColor=050608&color=00B7FF)
   [![GitHub Sponsors](https://img.shields.io/github/sponsors/smnandre?logo=githubsponsors&logoColor=00B7FF&label=%20Sponsor&labelColor=050608&color=00B7FF)](https://github.com/sponsors/smnandre)
 
-CodeKit connects CodeSlicer, CodeHighlight, and CodeSnippet. It selects source code, derives semantic
+Code Kit connects Code Slicer, Code Highlight, and Code Snippet. It selects source code, derives semantic
 syntax annotations, and returns a renderer-independent snippet while preserving source context.
 
 ```php
@@ -32,11 +32,11 @@ Install ALTO CodeKit with Composer:
 composer require alto/code-kit
 ```
 
-CodeKit requires PHP 8.4 or later. It installs CodeSlicer, CodeHighlight, and CodeSnippet.
+Code Kit requires PHP 8.4 or later. It installs Code Slicer, Code Highlight, and Code Snippet.
 
 ## Complete-source parsing
 
-CodeKit parses the complete source before projecting the selected range. Context-sensitive syntax
+Code Kit parses the complete source before projecting the selected range. Context-sensitive syntax
 therefore remains correct when a slice starts inside a docblock, string, heredoc, or embedded
 language.
 
@@ -74,11 +74,12 @@ unannotated.
 
 ## Package boundary
 
-CodeKit owns orchestration only. CodeSlicer locates source ranges, CodeHighlight parses syntax, and
-CodeSnippet carries the immutable result. Rendering to HTML, SVG, PNG, terminals, or slides belongs
+Code Kit owns orchestration only. Code Slicer locates source ranges, Code Highlight parses syntax, and
+Code Snippet carries the immutable result. Rendering to HTML, SVG, PNG, terminals, or slides belongs
 to consumers.
 
-See the [documentation](docs/index.md) for installation, a guided example, and the public API.
+Read the [documentation](docs/index.md), then continue with
+[Installation](docs/installation.md) and [Getting started](docs/getting-started.md).
 
 ## Contributing
 

docs/getting-started.md

@@ -1,35 +1,85 @@
 # Getting started
 
-Select a source region, then turn it into an annotated snippet:
+After [installation](installation.md), save this as `snippet.php` beside
+`vendor/` and run `php snippet.php`. The input is included, so the example does
+not depend on an external source file.
 
 ```php
+<?php
+
+require __DIR__.'/vendor/autoload.php';
+
 use Alto\Code\Kit\CodeKit;
 use Alto\Code\Slicer\CodeSource;
 
-$slice = CodeSource::fromFile('src/Command/BuildCommand.php')
-    ->slice()
-    ->method('execute');
+$code = <<<'PHP'
+<?php
+$total = 42;
+return $total;
+PHP;
 
-$snippet = (new CodeKit())
-    ->snippet($slice)
-    ->dedent();
-```
+$source = CodeSource::fromString($code, 'php', 'checkout.php');
+$snippet = (new CodeKit())->snippet($source->lines(2, 2));
 
-CodeKit parses the complete source before projecting the selected range. Context-sensitive syntax
-therefore remains correct when a slice starts inside a docblock, string, heredoc, or embedded
-language.
+printf("%s:%d\n", $snippet->sourceName(), $snippet->startLine());
+echo $snippet->code(), "\n";
 
-Use `annotate()` when a `CodeSnippet` already exists:
+foreach ($snippet->annotations() as $annotation) {
+    printf(
+        "%s => %s/%s\n",
+        substr($snippet->code(), $annotation->offset, $annotation->length),
+        $annotation->data['scope'],
+        $annotation->data['tokenType'],
+    );
+}
+```
 
-```php
-$annotated = (new CodeKit())->annotate($snippet);
+The script prints:
+
+```text
+checkout.php:2
+$total = 42;
+$total => variable/unknown
+= => operator/unknown
+42 => number/unknown
+; => punctuation/unknown
 ```
 
-Pass a language slug directly and use the same start and end line to return one line without
-adjacent context:
+The result retains the source name and original line number. Its annotations
+carry semantic scope and token type data; they do not contain rendered HTML.
+
+## Create a snippet
+
+`CodeKit::snippet()` accepts a `CodeSlice`. It parses the complete source,
+creates syntax annotations, and then projects the selected byte range into a
+`CodeSnippet`. Complete-source parsing preserves context when a slice starts
+inside a docblock, string, heredoc, or embedded language.
 
 ```php
-$line = (new CodeKit())->snippet(
+$snippet = (new CodeKit())->snippet(
     CodeSource::fromString($code, 'php')->lines(24, 24),
 );
 ```
+
+The source language controls parsing. When it is absent or unsupported, consult
+the Code Highlight language documentation before changing the selected range.
+
+## Annotate a snippet
+
+Use `annotate()` when a `CodeSnippet` already exists:
+
+```php
+use Alto\Code\Snippet\CodeSnippet;
+
+$snippet = CodeSnippet::fromCode('$total = array_sum($prices);', 'php');
+$annotated = (new CodeKit())->annotate($snippet);
+```
+
+The method parses the snippet code and returns a new value containing `syntax`
+annotations. Existing metadata, selections, and annotations remain available.
+Each syntax annotation contains the semantic `scope` and `tokenType` supplied
+by Code Highlight; whitespace is left unannotated.
+
+Unlike `snippet()`, `annotate()` only has the snippet content as parsing
+context. Use `snippet()` with a source slice when the selected code begins
+inside context established earlier in the file.

docs/index.md

@@ -1,10 +1,29 @@
-# CodeKit
+# Alto Code Kit
 
-CodeKit composes source selection, semantic parsing, and immutable annotated snippets.
+ALTO Code Kit combines source selection, semantic parsing, and immutable
+snippet data. It parses a complete source before projecting the selected range,
+so a slice retains the context required to recognize comments, strings,
+heredocs, and embedded languages.
 
-- [Installation](installation.md)
-- [Getting started](getting-started.md)
-- [Public API](public-api.md)
+```php
+use Alto\Code\Kit\CodeKit;
+use Alto\Code\Slicer\CodeSource;
 
-The package is the integration boundary between CodeSlicer, CodeHighlight, and CodeSnippet. It does
-not define source selectors, syntax parsers, snippet values, or renderers.
+$source = CodeSource::fromString("<?php\nreturn 42;\n", 'php', 'answer.php');
+$snippet = (new CodeKit())->snippet($source->lines(2, 2));
+echo $snippet->code();
+```
+
+The example prints `return 42;` and the returned `CodeSnippet` carries syntax
+annotations for its tokens.
+
+## Documentation
+
+- [Installation](installation.md): install Code Kit and its three component packages.
+- [Getting started](getting-started.md): create or annotate a portable code snippet.
+
+## Boundaries
+
+Code Slicer owns source selection, Code Highlight owns syntax parsing, and Code
+Snippet owns the immutable result. Code Kit composes them. Rendering to HTML,
+SVG, PNG, terminals, or slides remains the responsibility of consumers.

docs/installation.md

@@ -1,10 +1,10 @@
 # Installation
 
-Install CodeKit with Composer:
+Install ALTO Code Kit with Composer:
 
 ```bash
 composer require alto/code-kit
 ```
 
-CodeKit requires PHP 8.4 or later. It installs CodeSlicer, CodeHighlight, and CodeSnippet as runtime
-dependencies.
+ALTO Code Kit requires PHP 8.4 or later. It installs ALTO Code Slicer, Code
+Highlight, and Code Snippet as runtime dependencies.