fix README: correct flag docs and add version command

Author: dmoose

HOWTO.md

@@ -55,29 +55,9 @@ This creates a vocabulary that both humans and LLMs can use consistently.
 
 ### Three-Layer Design
 
-tokenctl supports a three-layer architecture that enforces clean separation:
-
-```
-┌─────────────────────────────────────────────────────┐
-│                   COMPONENT LAYER                   │
-│  btn-bg, card-padding, input-border-radius          │
-│  Can only reference: semantic tokens                │
-└───────────────────────┬─────────────────────────────┘
-                        │ references
-┌───────────────────────▼─────────────────────────────┐
-│                   SEMANTIC LAYER                    │
-│  primary, success, error, spacing-md                │
-│  Can reference: brand tokens                        │
-└───────────────────────┬─────────────────────────────┘
-                        │ references
-┌───────────────────────▼─────────────────────────────┐
-│                    BRAND LAYER                      │
-│  blue-500, gray-100, 1rem, 400                      │
-│  Raw values only (no references)                    │
-└─────────────────────────────────────────────────────┘
-```
-
-### Layer Definitions
+tokenctl uses a three-layer architecture: Brand (raw values) → Semantic (meaning) → Component (usage). See [TOKENS.md](TOKENS.md#token-architecture) for the full diagram, rationale, and layer reference rules.
+
+### Layer Example
 
 ```json
 {
@@ -104,24 +84,6 @@ tokenctl supports a three-layer architecture that enforces clean separation:
 }
 ```
 
-### Why Layers Matter
-
-**Without layers:**
-```css
-/* Component directly references raw value - tight coupling */
-.btn { background: #3b82f6; }
-```
-
-**With layers:**
-```css
-/* Component references semantic token - loose coupling */
-.btn { background: var(--component-btn-bg); }
-```
-
-When you change your brand color from blue to purple:
-- **Without layers:** Find and replace across entire codebase
-- **With layers:** Change `semantic.primary` reference, everything updates
-
 ---
 
 ## Getting Started

README.md

@@ -49,7 +49,9 @@ Creates:
 my-design-system/
 ├── tokens/
 │   ├── brand/colors.json
+│   ├── surface/
 │   ├── semantic/status.json
+│   ├── typography/
 │   ├── spacing/scale.json
 │   └── themes/
 ```
@@ -192,13 +194,14 @@ tokenctl build [dir...]                # Build artifacts (multi-dir merge)
   --customizable-only                # Only tokens marked $customizable: true
 
 tokenctl validate [dir...]             # Validate tokens (multi-dir merge)
-  --strict                           # Fail on warnings
   --strict-layers                    # Enforce layer reference rules
 
 tokenctl search [query]                # Search tokens
   --type=<type>                      # Filter by type (color, dimension, etc.)
   --category=<cat>                   # Filter by category
   --dir=<dir>                        # Token directory (default: .)
+
+tokenctl version                       # Print version information
 ```
 
 ## Catalog Format (v2.1)