IncludeCPP 4.3.0__py3-none-any.whl → 4.6.0__py3-none-any.whl

includecpp/cli/commands.py

@@ -16,6 +16,36 @@ from .config_parser import CppProjectConfig
 colorama_init()
 
 
+def _preprocess_doc_option():
+    """
+    Preprocess sys.argv to handle --doc with optional value.
+    Converts: --doc (alone) -> --doc ""
+    Keeps: --doc "term" -> --doc "term"
+    """
+    args = sys.argv[:]
+    new_args = []
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == '--doc':
+            new_args.append(arg)
+            # Check if next arg exists and is not another option
+            if i + 1 < len(args) and not args[i + 1].startswith('-'):
+                new_args.append(args[i + 1])
+                i += 1
+            else:
+                # No value provided - add empty string
+                new_args.append('')
+        else:
+            new_args.append(arg)
+        i += 1
+    sys.argv[:] = new_args
+
+
+# Preprocess before Click parses arguments
+_preprocess_doc_option()
+
+
 def _is_experimental_enabled() -> bool:
     """Check if experimental features (cppy, ai) are enabled."""
     config_path = Path.home() / '.includecpp' / '.secret'
@@ -262,15 +292,48 @@ def _show_changelog(count: int = 2, show_all: bool = False):
 
 
 def _get_doc_path():
-    """Get path to DOCUMENTATION.md file."""
+    """Get path to README.md or DOCUMENTATION.md file."""
     package_dir = Path(__file__).parent.parent
+
+    # 1. Check if running from development (project root has README.md)
+    project_root = package_dir.parent
+    readme_path = project_root / 'README.md'
+    if readme_path.exists() and (project_root / 'pyproject.toml').exists():
+        # We're in development mode - use project README
+        return readme_path
+
+    # 2. DOCUMENTATION.md in package (installed package)
     doc_path = package_dir / 'DOCUMENTATION.md'
     if doc_path.exists():
         return doc_path
-    # Fallback to current directory
-    cwd_path = Path.cwd() / 'DOCUMENTATION.md'
-    if cwd_path.exists():
-        return cwd_path
+
+    # 3. README.md in package dir
+    readme_pkg = package_dir / 'README.md'
+    if readme_pkg.exists():
+        return readme_pkg
+
+    # 4. Try current working directory
+    cwd_readme = Path.cwd() / 'README.md'
+    if cwd_readme.exists():
+        return cwd_readme
+    cwd_doc = Path.cwd() / 'DOCUMENTATION.md'
+    if cwd_doc.exists():
+        return cwd_doc
+
+    # 5. Try using importlib.resources for installed package
+    try:
+        import importlib.resources as pkg_resources
+        try:
+            # Python 3.9+
+            files = pkg_resources.files('includecpp')
+            doc_file = files / 'DOCUMENTATION.md'
+            if doc_file.is_file():
+                return Path(str(doc_file))
+        except Exception:
+            pass
+    except ImportError:
+        pass
+
     return None
 
 
@@ -368,7 +431,8 @@ def _show_doc(search_term: str = None):
 
 
 @click.group(invoke_without_command=True)
-@click.option('--doc', 'doc_search', is_flag=False, flag_value='__SHOW_ALL__', default=None, help='Show documentation. Use --doc "term" to search.')
+@click.option('--doc', 'doc_search', default=None, help='Show documentation. Use --doc or --doc "term" to search.')
+@click.option('-d', 'doc_flag', is_flag=True, help='Show full documentation (shorthand)')
 @click.option('--changelog', 'show_changelog', is_flag=True, help='Show changelog (last 2 releases by default)')
 @click.option('--all', 'changelog_all', is_flag=True, help='Show all changelog entries (use with --changelog)')
 @click.option('--1', 'changelog_1', is_flag=True, hidden=True)
@@ -382,7 +446,7 @@ def _show_doc(search_term: str = None):
 @click.option('--9', 'changelog_9', is_flag=True, hidden=True)
 @click.option('--10', 'changelog_10', is_flag=True, hidden=True)
 @click.pass_context
-def cli(ctx, doc_search, show_changelog, changelog_all, changelog_1, changelog_2, changelog_3,
+def cli(ctx, doc_search, doc_flag, show_changelog, changelog_all, changelog_1, changelog_2, changelog_3,
         changelog_4, changelog_5, changelog_6, changelog_7, changelog_8, changelog_9, changelog_10):
     """IncludeCPP - C++ Performance in Python, Zero Hassle
 
@@ -418,9 +482,10 @@ def cli(ctx, doc_search, show_changelog, changelog_all, changelog_1, changelog_2
             _show_changelog(count=count)
         ctx.exit(0)
 
-    # Handle documentation - --doc or --doc "search"
-    if doc_search is not None:
-        search_term = None if doc_search == '__SHOW_ALL__' else doc_search
+    # Handle documentation - --doc "search" or -d (flag)
+    if doc_search is not None or doc_flag:
+        # Empty string from --doc without value should show full docs (like None)
+        search_term = doc_search if doc_search else None
         _show_doc(search_term)
         ctx.exit(0)
 
@@ -2630,7 +2695,8 @@ def plugin(plugin_name, files, private):
         method_regex = re.compile(
             r'(?:(?:virtual|static|inline|explicit|constexpr)\s+)*'  # Optional modifiers
             r'(?:const\s+)?'  # Optional const before return type
-            r'([a-zA-Z_][\w:]*(?:<[^<>]*(?:<[^<>]*>[^<>]*)*>)?(?:\s*[&*])?)\s+'  # Return type (must start with letter/underscore, handles nested templates)
+            r'((?:(?:unsigned|signed|long|short)\s+)*'  # v4.3.2: Handle multi-word types (unsigned long long, etc.)
+            r'[a-zA-Z_][\w:]*(?:<[^<>]*(?:<[^<>]*>[^<>]*)*>)?(?:\s*[&*])?)\s+'  # Return type (handles nested templates)
             r'(\w+)\s*'  # Method name
             r'\(([^)]*)\)\s*'  # Parameters (captured in group 3)
             r'(const)?'  # Const qualifier after params (captured in group 4)
@@ -7737,26 +7803,1082 @@ def cssl_makemodule(path, output):
     click.echo(f"  Type: {module_data['type']}")
 
 
+# ============================================================================
+# CSSL Documentation Category Helpers
+# ============================================================================
+
+def _show_doc_categories():
+    """Show overview of all CSSL syntax categories."""
+    click.secho("CSSL Syntax Categories", fg='cyan', bold=True)
+    click.secho("=" * 60, fg='cyan')
+    click.echo()
+
+    categories = [
+        ("--snapshots, -s", "%", "Captured variable snapshots", "yellow"),
+        ("--references, -r", "&", "Function/variable references", "green"),
+        ("--overrides, -o", "++, embedded, &<>", "Override/replacement syntax", "magenta"),
+        ("--datatypes, -t", "string, int, ...", "Data types", "blue"),
+        ("--keywords, -k", "if, for, class, ...", "All keywords", "cyan"),
+        ("--operators", "<==, <<==, +, ...", "All operators", "yellow"),
+        ("--containers, -c", "stack<T>, vector<T>, ...", "Container types", "green"),
+        ("--globals", "@, global", "Global variables", "magenta"),
+        ("--injection, -i", "<==, <<==, +<==", "Code injection", "red"),
+        ("--open", "open, OpenFind", "Open parameters", "blue"),
+        ("--embedded, -e", "embedded", "Function/class replacement", "magenta"),
+        ("--classes", "class, extends, ...", "OOP syntax", "cyan"),
+        ("--enums", "enum, Enum::Value", "Enumerated types", "yellow"),
+        ("--exceptions, -x", "try, catch, throw", "Exception handling", "red"),
+        ("--modifiers, -m", "const, private, ...", "Access/type modifiers", "blue"),
+        ("--builtins, -b", "printl, json::, ...", "Built-in functions", "green"),
+    ]
+
+    for flag, symbols, desc, color in categories:
+        click.echo(f"  {click.style(flag, fg=color, bold=True):30} ", nl=False)
+        click.echo(f"{click.style(symbols, fg='white'):25} ", nl=False)
+        click.echo(f"{desc}")
+
+    click.echo()
+    click.secho("Usage:", fg='cyan')
+    click.echo("  includecpp cssl doc --snapshots    # Show % documentation")
+    click.echo("  includecpp cssl doc --embedded     # Show embedded docs")
+    click.echo("  includecpp cssl doc \"keyword\"      # Search documentation")
+
+
+def _show_doc_snapshots():
+    """Show % snapshot syntax documentation."""
+    click.secho("% - Captured Variable Snapshots", fg='yellow', bold=True)
+    click.secho("=" * 60, fg='yellow')
+    click.echo()
+
+    click.secho("Description:", fg='cyan')
+    click.echo("  The % prefix captures the current value of a variable or function")
+    click.echo("  at definition time. Used in embedded functions to preserve the")
+    click.echo("  original function before replacement.")
+    click.echo()
+
+    click.secho("Syntax:", fg='cyan')
+    click.echo("  %variable      - Captured value of 'variable'")
+    click.echo("  %function()    - Call the original function (before embedding)")
+    click.echo()
+
+    click.secho("Examples:", fg='cyan')
+    click.echo()
+    click.secho("  // In embedded function, call original:", fg='white')
+    click.echo("  embedded define MyPrint(text) &print {")
+    click.echo("      %print(\"[LOG] \" + text);  // Call original print")
+    click.echo("  }")
+    click.echo()
+    click.secho("  // Capture variable value:", fg='white')
+    click.echo("  x = 10;")
+    click.echo("  define test() {")
+    click.echo("      captured = %x;  // Captures current value of x")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Use Cases:", fg='cyan')
+    click.echo("  - Wrapping built-in functions with logging")
+    click.echo("  - Preserving original behavior while adding functionality")
+    click.echo("  - Creating function decorators/middleware")
+
+
+def _show_doc_references():
+    """Show & reference syntax documentation."""
+    click.secho("& - References", fg='green', bold=True)
+    click.secho("=" * 60, fg='green')
+    click.echo()
+
+    click.secho("Description:", fg='cyan')
+    click.echo("  The & prefix creates references to functions, variables, or")
+    click.echo("  specifies the function being replaced in embedded definitions.")
+    click.echo()
+
+    click.secho("Syntax:", fg='cyan')
+    click.echo("  &function         - Reference to function (for embedded)")
+    click.echo("  &variable         - Reference to variable")
+    click.echo("  &ClassName        - Reference to class")
+    click.echo("  &$PyObject        - Reference to Python object")
+    click.echo()
+
+    click.secho("Examples:", fg='cyan')
+    click.echo()
+    click.secho("  // Embedded function replacement:", fg='white')
+    click.echo("  embedded define Logger(msg) &printl {")
+    click.echo("      %printl(\"[\" + timestamp() + \"] \" + msg);")
+    click.echo("  }")
+    click.echo()
+    click.secho("  // Function reference:", fg='white')
+    click.echo("  callback = &myFunction;")
+    click.echo("  callback();  // Calls myFunction")
+    click.echo()
+    click.secho("  // In open param switch conditions:", fg='white')
+    click.echo("  switch(Params) {")
+    click.echo("      case error & !text:  // error exists AND text doesn't")
+    click.echo("          handleError();")
+    click.echo("  }")
+
+
+def _show_doc_overrides():
+    """Show override/replacement syntax documentation."""
+    click.secho("Overrides - ++, embedded, &<>", fg='magenta', bold=True)
+    click.secho("=" * 60, fg='magenta')
+    click.echo()
+
+    click.secho("1. embedded - Function/Class Replacement", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  Replaces an existing function or class with a new implementation.")
+    click.echo()
+    click.echo("  Syntax:")
+    click.echo("    embedded define NewName(args) &OldFunc { ... }")
+    click.echo("    embedded class NewClass &OldClass { ... }")
+    click.echo("    embedded NewEnum &OldEnum { ... }  // Enum replacement")
+    click.echo()
+    click.echo("  Example:")
+    click.echo("    embedded define SafePrint(text) &print {")
+    click.echo("        if (text != null) {")
+    click.echo("            %print(text);  // Call original")
+    click.echo("        }")
+    click.echo("    }")
+    click.echo()
+
+    click.secho("2. ++ - Constructor/Method Extension", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  Appends code to existing constructors or methods.")
+    click.echo()
+    click.echo("  Syntax:")
+    click.echo("    ClassName::constr ++ { additional code }")
+    click.echo("    ClassName::method ++ { additional code }")
+    click.echo()
+    click.echo("  Example:")
+    click.echo("    Player::constr ++ {")
+    click.echo("        this->initialized = true;")
+    click.echo("        printl(\"Player created!\");")
+    click.echo("    }")
+    click.echo()
+
+    click.secho("3. open embedded define - Open Parameter Wrapper", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  Create wrapper with flexible open parameters.")
+    click.echo()
+    click.echo("  Syntax:")
+    click.echo("    open embedded define Name(open Params) &target { ... }")
+    click.echo("    embedded open define Name(open Params) &target { ... }")
+    click.echo()
+    click.echo("  Example:")
+    click.echo("    open embedded define SmartPrint(open Args) &printl {")
+    click.echo("        text = OpenFind<string>(0);")
+    click.echo("        error = OpenFind<string, \"error\">;")
+    click.echo("        switch(Args) {")
+    click.echo("            case error: %printl(\"ERROR: \" + error);")
+    click.echo("            default: %printl(text);")
+    click.echo("        }")
+    click.echo("    }")
+
+
+def _show_doc_datatypes():
+    """Show data types documentation."""
+    click.secho("Data Types", fg='blue', bold=True)
+    click.secho("=" * 60, fg='blue')
+    click.echo()
+
+    click.secho("Primitive Types:", fg='cyan')
+    click.echo("  string    - Text strings: \"hello\", 'world'")
+    click.echo("  int       - Integers: 42, -10, 0x1F")
+    click.echo("  float     - Floating point: 3.14, -0.5")
+    click.echo("  bool      - Boolean: true, false")
+    click.echo("  null      - Null value: null, None")
+    click.echo("  dynamic   - Any type (type inference)")
+    click.echo("  void      - No return value (functions)")
+    click.echo()
+
+    click.secho("Container Types:", fg='cyan')
+    click.echo("  array<T>      - Fixed-size array")
+    click.echo("  list<T>       - Dynamic list (alias: vector<T>)")
+    click.echo("  stack<T>      - LIFO stack")
+    click.echo("  vector<T>     - Dynamic array")
+    click.echo("  map<K,V>      - Key-value dictionary")
+    click.echo("  set<T>        - Unique elements set")
+    click.echo("  combo<T>      - Combination container")
+    click.echo("  iterator<T>   - Iterator object")
+    click.echo("  datastruct<T> - Custom data structure")
+    click.echo()
+
+    click.secho("Special Types:", fg='cyan')
+    click.echo("  json          - JSON object")
+    click.echo("  regex         - Regular expression")
+    click.echo("  callable      - Function reference")
+    click.echo("  object        - Generic object")
+    click.echo()
+
+    click.secho("Type Declaration:", fg='cyan')
+    click.echo("  string name = \"John\";")
+    click.echo("  int count = 0;")
+    click.echo("  dynamic value = getAny();")
+    click.echo("  list<string> names = [\"a\", \"b\"];")
+    click.echo("  map<string, int> scores = {\"a\": 10};")
+
+
+def _show_doc_keywords():
+    """Show all CSSL keywords."""
+    click.secho("CSSL Keywords", fg='cyan', bold=True)
+    click.secho("=" * 60, fg='cyan')
+    click.echo()
+
+    click.secho("Control Flow:", fg='yellow')
+    click.echo("  if, elif, else       - Conditionals")
+    click.echo("  for, foreach, while  - Loops")
+    click.echo("  switch, case, default - Pattern matching")
+    click.echo("  break, continue      - Loop control")
+    click.echo("  return               - Function return")
+    click.echo("  try, catch, finally  - Exception handling")
+    click.echo("  throw                - Raise exception")
+    click.echo()
+
+    click.secho("Functions:", fg='yellow')
+    click.echo("  define       - Define function: define name() { }")
+    click.echo("  void         - No return type: void name() { }")
+    click.echo("  shuffled     - Randomized function")
+    click.echo("  open         - Open/variadic parameters")
+    click.echo("  closed       - No variadic params")
+    click.echo()
+
+    click.secho("Classes:", fg='yellow')
+    click.echo("  class        - Define class: class Name { }")
+    click.echo("  struct       - Define struct")
+    click.echo("  enum         - Define enum: enum Name { A, B }")
+    click.echo("  interface    - Define interface")
+    click.echo("  extends      - Inherit from class")
+    click.echo("  overwrites   - Override parent class")
+    click.echo("  constr       - Constructor")
+    click.echo("  new          - Create instance: new ClassName()")
+    click.echo("  this         - Current instance reference")
+    click.echo("  super        - Parent class reference")
+    click.echo()
+
+    click.secho("Modifiers:", fg='yellow')
+    click.echo("  embedded     - Replace existing function/class")
+    click.echo("  global       - Global variable declaration")
+    click.echo("  private      - Private member")
+    click.echo("  protected    - Protected member")
+    click.echo("  public       - Public member")
+    click.echo("  static       - Static member")
+    click.echo("  const        - Constant value")
+    click.echo("  final        - Cannot be overridden")
+    click.echo("  virtual      - Virtual method")
+    click.echo("  abstract     - Abstract class/method")
+    click.echo()
+
+    click.secho("Special:", fg='yellow')
+    click.echo("  payload      - Load payload file")
+    click.echo("  include      - Include CSSL file")
+    click.echo("  import       - Import module")
+    click.echo("  bytearrayed  - Multi-return analysis")
+    click.echo("  in           - Iteration/membership")
+    click.echo("  range        - Number range")
+
+
+def _show_doc_operators():
+    """Show all CSSL operators."""
+    click.secho("CSSL Operators", fg='yellow', bold=True)
+    click.secho("=" * 60, fg='yellow')
+    click.echo()
+
+    click.secho("Arithmetic:", fg='cyan')
+    click.echo("  +   Addition / String concatenation")
+    click.echo("  -   Subtraction")
+    click.echo("  *   Multiplication")
+    click.echo("  /   Division")
+    click.echo("  %   Modulo (also: captured variable prefix)")
+    click.echo("  **  Power/exponentiation")
+    click.echo("  ++  Increment / Constructor extension")
+    click.echo("  --  Decrement")
+    click.echo()
+
+    click.secho("Comparison:", fg='cyan')
+    click.echo("  ==  Equal")
+    click.echo("  !=  Not equal")
+    click.echo("  <   Less than")
+    click.echo("  >   Greater than")
+    click.echo("  <=  Less or equal")
+    click.echo("  >=  Greater or equal")
+    click.echo()
+
+    click.secho("Logical:", fg='cyan')
+    click.echo("  &&  Logical AND")
+    click.echo("  ||  Logical OR")
+    click.echo("  !   Logical NOT")
+    click.echo("  &   Bitwise AND / Reference / Param condition AND")
+    click.echo("  |   Bitwise OR")
+    click.echo("  not Keyword NOT")
+    click.echo()
+
+    click.secho("Assignment:", fg='cyan')
+    click.echo("  =   Assign")
+    click.echo("  +=  Add and assign")
+    click.echo("  -=  Subtract and assign")
+    click.echo("  *=  Multiply and assign")
+    click.echo("  /=  Divide and assign")
+    click.echo()
+
+    click.secho("Injection/Infusion:", fg='cyan')
+    click.echo("  <==   BruteInjection (replace method body)")
+    click.echo("  +<==  Append to method body")
+    click.echo("  -<==  Prepend to method body")
+    click.echo("  <<==  CodeInfusion (replace, preserves context)")
+    click.echo("  +<<== Append with CodeInfusion")
+    click.echo()
+
+    click.secho("Access:", fg='cyan')
+    click.echo("  .     Member access: obj.property")
+    click.echo("  ->    Member access: this->property")
+    click.echo("  ::    Namespace/static: Class::method, json::parse")
+    click.echo("  @     Global variable: @globalVar")
+    click.echo("  $     Shared object: $sharedName")
+    click.echo("  %     Captured/snapshot: %originalFunc")
+    click.echo("  &     Reference: &function, &variable")
+    click.echo("  #$    Python interop: #$python_var")
+
+
+def _show_doc_containers():
+    """Show container types documentation."""
+    click.secho("Container Types", fg='green', bold=True)
+    click.secho("=" * 60, fg='green')
+    click.echo()
+
+    click.secho("stack<T> - LIFO Stack", fg='cyan')
+    click.echo("-" * 30)
+    click.echo("  stack<int> s;")
+    click.echo("  s.push(10);")
+    click.echo("  s.push(20);")
+    click.echo("  x = s.pop();    // 20")
+    click.echo("  y = s.peek();   // 10")
+    click.echo("  n = s.size();   // 1")
+    click.echo()
+
+    click.secho("vector<T> / list<T> - Dynamic Array", fg='cyan')
+    click.echo("-" * 30)
+    click.echo("  vector<string> v = [\"a\", \"b\", \"c\"];")
+    click.echo("  v.push(\"d\");")
+    click.echo("  v.insert(0, \"start\");")
+    click.echo("  x = v[1];       // \"a\"")
+    click.echo("  v.remove(0);")
+    click.echo("  for (item in v) { printl(item); }")
+    click.echo()
+
+    click.secho("map<K,V> - Dictionary", fg='cyan')
+    click.echo("-" * 30)
+    click.echo("  map<string, int> m = {\"score\": 100};")
+    click.echo("  m[\"lives\"] = 3;")
+    click.echo("  m.set(\"level\", 1);")
+    click.echo("  x = m.get(\"score\");  // 100")
+    click.echo("  if (m.has(\"lives\")) { ... }")
+    click.echo("  keys = m.keys();")
+    click.echo("  vals = m.values();")
+    click.echo()
+
+    click.secho("set<T> - Unique Set", fg='cyan')
+    click.echo("-" * 30)
+    click.echo("  set<int> s = {1, 2, 3};")
+    click.echo("  s.add(4);")
+    click.echo("  s.add(2);      // No duplicate")
+    click.echo("  if (s.contains(3)) { ... }")
+    click.echo("  s.remove(1);")
+    click.echo()
+
+    click.secho("array<T> - Fixed Array", fg='cyan')
+    click.echo("-" * 30)
+    click.echo("  array<int> a = [1, 2, 3, 4, 5];")
+    click.echo("  x = a[0];")
+    click.echo("  a[2] = 10;")
+    click.echo("  n = a.length();")
+
+
+def _show_doc_globals():
+    """Show global variable documentation."""
+    click.secho("@ - Global Variables", fg='magenta', bold=True)
+    click.secho("=" * 60, fg='magenta')
+    click.echo()
+
+    click.secho("Description:", fg='cyan')
+    click.echo("  Global variables are accessible from anywhere in the code.")
+    click.echo("  Declare with 'global' keyword, access with '@' prefix.")
+    click.echo()
+
+    click.secho("Declaration:", fg='cyan')
+    click.echo("  global version = \"1.0.0\";")
+    click.echo("  global config = {\"debug\": true};")
+    click.echo("  global counter = 0;")
+    click.echo()
+
+    click.secho("Access:", fg='cyan')
+    click.echo("  printl(@version);        // \"1.0.0\"")
+    click.echo("  @counter = @counter + 1;")
+    click.echo("  if (@config[\"debug\"]) { ... }")
+    click.echo()
+
+    click.secho("In Payloads:", fg='cyan')
+    click.echo("  // file.cssl-pl")
+    click.echo("  global appName = \"MyApp\";")
+    click.echo("  global settings = {")
+    click.echo("      \"theme\": \"dark\",")
+    click.echo("      \"lang\": \"en\"")
+    click.echo("  };")
+    click.echo()
+    click.echo("  // main.cssl")
+    click.echo("  payload(\"file.cssl-pl\");")
+    click.echo("  printl(@appName);  // \"MyApp\"")
+    click.echo()
+
+    click.secho("Namespaced Globals:", fg='cyan')
+    click.echo("  payload(\"engine.cssl-pl\", \"Engine\");")
+    click.echo("  printl(@Engine::version);")
+
+
+def _show_doc_injection():
+    """Show code injection operators documentation."""
+    click.secho("Code Injection Operators", fg='red', bold=True)
+    click.secho("=" * 60, fg='red')
+    click.echo()
+
+    click.secho("<== BruteInjection (Replace)", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  Completely replaces a method body.")
+    click.echo()
+    click.echo("  Syntax: ClassName::method <== { new body }")
+    click.echo()
+    click.echo("  Example:")
+    click.echo("    Player::update <== {")
+    click.echo("        // Completely new implementation")
+    click.echo("        this->x += this->speed;")
+    click.echo("    }")
+    click.echo()
+
+    click.secho("+<== BruteInjection (Append)", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  Appends code to end of existing method.")
+    click.echo()
+    click.echo("  Syntax: ClassName::method +<== { appended code }")
+    click.echo()
+    click.echo("  Example:")
+    click.echo("    Player::update +<== {")
+    click.echo("        // This runs after original update()")
+    click.echo("        this->checkBounds();")
+    click.echo("    }")
+    click.echo()
+
+    click.secho("-<== BruteInjection (Prepend)", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  Prepends code to start of existing method.")
+    click.echo()
+    click.echo("  Syntax: ClassName::method -<== { prepended code }")
+    click.echo()
+    click.echo("  Example:")
+    click.echo("    Player::update -<== {")
+    click.echo("        // This runs before original update()")
+    click.echo("        this->validateState();")
+    click.echo("    }")
+    click.echo()
+
+    click.secho("<<== CodeInfusion (Contextual Replace)", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  Like <== but preserves class context (this, super).")
+    click.echo()
+    click.echo("  Syntax: ClassName::method <<== { new body }")
+    click.echo()
+    click.echo("  Example:")
+    click.echo("    Enemy::attack <<== {")
+    click.echo("        // Has access to this-> context")
+    click.echo("        this->damage = this->baseDamage * 2;")
+    click.echo("        super::attack();  // Call parent")
+    click.echo("    }")
+
+
+def _show_doc_open():
+    """Show open parameters documentation."""
+    click.secho("open - Open/Variadic Parameters", fg='blue', bold=True)
+    click.secho("=" * 60, fg='blue')
+    click.echo()
+
+    click.secho("Description:", fg='cyan')
+    click.echo("  'open' allows functions to accept any number/type of arguments.")
+    click.echo("  Use OpenFind to extract values by index or name.")
+    click.echo()
+
+    click.secho("Function Declaration:", fg='cyan')
+    click.echo("  define myFunc(open Params) { ... }")
+    click.echo("  open define wrapper(open Args) &target { ... }")
+    click.echo()
+
+    click.secho("OpenFind - Extract Arguments:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  // By index (positional args):")
+    click.echo("  first = OpenFind<string>(0);   // 1st arg as string")
+    click.echo("  second = OpenFind<int>(1);     // 2nd arg as int")
+    click.echo()
+    click.echo("  // By name (keyword args):")
+    click.echo("  name = OpenFind<string, \"name\">;")
+    click.echo("  count = OpenFind<int, \"count\">;")
+    click.echo()
+
+    click.secho("switch(Params) - Parameter Matching:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  switch(Params) {")
+    click.echo("      case error & !text:     // error exists, text doesn't")
+    click.echo("          handleError();")
+    click.echo("          break;")
+    click.echo("      case text & !error:     // text exists, error doesn't")
+    click.echo("          printl(text);")
+    click.echo("          break;")
+    click.echo("      case name || id:        // name OR id exists")
+    click.echo("          lookup();")
+    click.echo("          break;")
+    click.echo("      default:")
+    click.echo("          printl(\"Unknown\");")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Complete Example:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  open embedded define SmartLog(open Input) &printl {")
+    click.echo("      msg = OpenFind<string>(0);")
+    click.echo("      level = OpenFind<string, \"level\">;")
+    click.echo("      switch(Input) {")
+    click.echo("          case level:")
+    click.echo("              %printl(\"[\" + level + \"] \" + msg);")
+    click.echo("              break;")
+    click.echo("          default:")
+    click.echo("              %printl(msg);")
+    click.echo("      }")
+    click.echo("  }")
+    click.echo()
+    click.echo("  // Usage:")
+    click.echo("  printl(\"Hello\");                    // Hello")
+    click.echo("  printl(\"Warning!\", level=\"WARN\");   // [WARN] Warning!")
+
+
+def _show_doc_embedded():
+    """Show embedded function/class replacement documentation."""
+    click.secho("embedded - Function/Class Replacement", fg='magenta', bold=True)
+    click.secho("=" * 60, fg='magenta')
+    click.echo()
+
+    click.secho("Description:", fg='cyan')
+    click.echo("  'embedded' replaces an existing function or class definition.")
+    click.echo("  The original can be called via %originalName().")
+    click.echo()
+
+    click.secho("Function Replacement:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  embedded define NewImpl(args) &oldFunction {")
+    click.echo("      // Your new implementation")
+    click.echo("      %oldFunction(args);  // Call original if needed")
+    click.echo("  }")
+    click.echo()
+    click.echo("  Example - Logging wrapper:")
+    click.echo("    embedded define Logger(msg) &print {")
+    click.echo("        timestamp = now();")
+    click.echo("        %print(\"[\" + timestamp + \"] \" + msg);")
+    click.echo("    }")
+    click.echo("    print(\"Hello\");  // Now prints with timestamp")
+    click.echo()
+
+    click.secho("With Open Parameters:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  Both syntaxes work:")
+    click.echo("    open embedded define Name(open P) &target { }")
+    click.echo("    embedded open define Name(open P) &target { }")
+    click.echo()
+    click.echo("  Example:")
+    click.echo("    open embedded define SafeDiv(open Args) &div {")
+    click.echo("        b = OpenFind<int>(1);")
+    click.echo("        if (b == 0) {")
+    click.echo("            return 0;  // Prevent division by zero")
+    click.echo("        }")
+    click.echo("        return %div(OpenFind<int>(0), b);")
+    click.echo("    }")
+    click.echo()
+
+    click.secho("Class Replacement:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  embedded class NewClass &OldClass {")
+    click.echo("      // New implementation")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Enum Replacement:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  embedded NewColors &Colors {")
+    click.echo("      RED = \"#FF0000\",")
+    click.echo("      GREEN = \"#00FF00\",")
+    click.echo("      BLUE = \"#0000FF\"")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Use Cases:", fg='cyan')
+    click.echo("  - Add logging/debugging to existing functions")
+    click.echo("  - Add validation/error handling")
+    click.echo("  - Implement middleware/interceptors")
+    click.echo("  - Mock functions for testing")
+    click.echo("  - Extend built-in functions (print, error, etc.)")
+
+
+def _show_doc_classes():
+    """Show class/OOP documentation."""
+    click.secho("Classes and OOP", fg='cyan', bold=True)
+    click.secho("=" * 60, fg='cyan')
+    click.echo()
+
+    click.secho("Class Definition:", fg='yellow')
+    click.echo("-" * 40)
+    click.echo("  class Player {")
+    click.echo("      string name;")
+    click.echo("      int health = 100;")
+    click.echo("      int score;")
+    click.echo()
+    click.echo("      constr Player(string n) {")
+    click.echo("          this->name = n;")
+    click.echo("          this->score = 0;")
+    click.echo("      }")
+    click.echo()
+    click.echo("      void takeDamage(int amount) {")
+    click.echo("          this->health -= amount;")
+    click.echo("      }")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Inheritance (extends):", fg='yellow')
+    click.echo("-" * 40)
+    click.echo("  class Enemy : extends Entity {")
+    click.echo("      int damage;")
+    click.echo()
+    click.echo("      constr Enemy(string name, int dmg) {")
+    click.echo("          super(name);  // Call parent constructor")
+    click.echo("          this->damage = dmg;")
+    click.echo("      }")
+    click.echo()
+    click.echo("      void attack(target) {")
+    click.echo("          target.takeDamage(this->damage);")
+    click.echo("      }")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Override (overwrites):", fg='yellow')
+    click.echo("-" * 40)
+    click.echo("  class Boss : overwrites Enemy {")
+    click.echo("      // Completely replaces Enemy class")
+    click.echo("      int health = 1000;")
+    click.echo()
+    click.echo("      void attack(target) {")
+    click.echo("          // New attack implementation")
+    click.echo("          super::attack(target);  // Optional: call parent")
+    click.echo("          target.takeDamage(this->damage * 2);")
+    click.echo("      }")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Instantiation:", fg='yellow')
+    click.echo("-" * 40)
+    click.echo("  player = new Player(\"Hero\");")
+    click.echo("  enemy = new Enemy(\"Goblin\", 10);")
+    click.echo()
+    click.echo("  // Namespaced class:")
+    click.echo("  engine = new Engine::GameEngine();")
+    click.echo()
+
+    click.secho("Constructor Extension (++):", fg='yellow')
+    click.echo("-" * 40)
+    click.echo("  Player::constr ++ {")
+    click.echo("      // Additional initialization")
+    click.echo("      this->initialized = true;")
+    click.echo("      printl(\"Player \" + this->name + \" created!\");")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Enums:", fg='yellow')
+    click.echo("-" * 40)
+    click.echo("  enum Direction {")
+    click.echo("      UP = 0,")
+    click.echo("      DOWN = 1,")
+    click.echo("      LEFT = 2,")
+    click.echo("      RIGHT = 3")
+    click.echo("  }")
+    click.echo()
+    click.echo("  dir = Direction.UP;")
+    click.echo("  if (dir == Direction.LEFT) { ... }")
+
+
+def _show_doc_enums():
+    """Show enum documentation."""
+    click.secho("Enums - Enumerated Types", fg='yellow', bold=True)
+    click.secho("=" * 60, fg='yellow')
+    click.echo()
+
+    click.secho("Basic Enum Definition:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  enum Direction {")
+    click.echo("      UP = 0,")
+    click.echo("      DOWN = 1,")
+    click.echo("      LEFT = 2,")
+    click.echo("      RIGHT = 3")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Enum Access (EnumName::Value):", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  dir = Direction::UP;")
+    click.echo("  // or")
+    click.echo("  dir = Direction.UP;")
+    click.echo()
+    click.echo("  if (dir == Direction::LEFT) {")
+    click.echo("      printl(\"Going left!\");")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("String Enums:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  enum Colors {")
+    click.echo("      RED = \"#FF0000\",")
+    click.echo("      GREEN = \"#00FF00\",")
+    click.echo("      BLUE = \"#0000FF\"")
+    click.echo("  }")
+    click.echo()
+    click.echo("  color = Colors::RED;  // \"#FF0000\"")
+    click.echo()
+
+    click.secho("Embedded Enum Replacement:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  // Replace existing enum")
+    click.echo("  embedded NewColors &Colors {")
+    click.echo("      RED = \"crimson\",")
+    click.echo("      GREEN = \"lime\",")
+    click.echo("      BLUE = \"navy\"")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Enum with Expressions:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  base = 100;")
+    click.echo("  enum Scores {")
+    click.echo("      LOW = base,")
+    click.echo("      MEDIUM = base * 2,")
+    click.echo("      HIGH = base * 5")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Enum Iteration:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  for (value in Direction) {")
+    click.echo("      printl(value);")
+    click.echo("  }")
+
+
+def _show_doc_exceptions():
+    """Show exception handling documentation."""
+    click.secho("Exception Handling", fg='red', bold=True)
+    click.secho("=" * 60, fg='red')
+    click.echo()
+
+    click.secho("try/catch/finally:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  try {")
+    click.echo("      result = riskyOperation();")
+    click.echo("      process(result);")
+    click.echo("  } catch (e) {")
+    click.echo("      printl(\"Error: \" + e);")
+    click.echo("  } finally {")
+    click.echo("      cleanup();")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("except (alias for catch):", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  try {")
+    click.echo("      data = json::parse(input);")
+    click.echo("  } except (err) {")
+    click.echo("      printl(\"Parse error: \" + err);")
+    click.echo("      data = {};")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("throw - Raise Exception:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  define divide(a, b) {")
+    click.echo("      if (b == 0) {")
+    click.echo("          throw \"Division by zero!\";")
+    click.echo("      }")
+    click.echo("      return a / b;")
+    click.echo("  }")
+    click.echo()
+    click.echo("  try {")
+    click.echo("      result = divide(10, 0);")
+    click.echo("  } catch (e) {")
+    click.echo("      printl(e);  // \"Division by zero!\"")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Catching Python Exceptions:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  try {")
+    click.echo("      // Python exceptions are also caught")
+    click.echo("      list = [1, 2, 3];")
+    click.echo("      x = list[10];  // IndexError")
+    click.echo("  } catch (e) {")
+    click.echo("      printl(\"Caught: \" + str(e));")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("Nested try/catch:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  try {")
+    click.echo("      try {")
+    click.echo("          innerOperation();")
+    click.echo("      } catch (inner) {")
+    click.echo("          throw \"Inner failed: \" + inner;")
+    click.echo("      }")
+    click.echo("  } catch (outer) {")
+    click.echo("      printl(outer);")
+    click.echo("  }")
+
+
+def _show_doc_modifiers():
+    """Show modifier keywords documentation."""
+    click.secho("Modifiers - Access and Type Qualifiers", fg='blue', bold=True)
+    click.secho("=" * 60, fg='blue')
+    click.echo()
+
+    click.secho("Access Modifiers:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  class MyClass {")
+    click.echo("      private int secret = 42;     // Only in class")
+    click.echo("      protected int data = 10;     // Class + subclasses")
+    click.echo("      public string name;          // Anywhere (default)")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("const - Immutable Values:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  const PI = 3.14159;")
+    click.echo("  const MAX_SIZE = 100;")
+    click.echo("  const CONFIG = {\"debug\": true};")
+    click.echo()
+    click.echo("  // Cannot reassign:")
+    click.echo("  PI = 3;  // Error!")
+    click.echo()
+
+    click.secho("static - Class-Level Members:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  class Counter {")
+    click.echo("      static int count = 0;")
+    click.echo()
+    click.echo("      constr Counter() {")
+    click.echo("          Counter::count += 1;")
+    click.echo("      }")
+    click.echo()
+    click.echo("      static int getCount() {")
+    click.echo("          return Counter::count;")
+    click.echo("      }")
+    click.echo("  }")
+    click.echo()
+    click.echo("  c1 = new Counter();")
+    click.echo("  c2 = new Counter();")
+    click.echo("  printl(Counter::getCount());  // 2")
+    click.echo()
+
+    click.secho("final - Cannot Override:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  class Base {")
+    click.echo("      final void important() {")
+    click.echo("          // Cannot be overridden in subclass")
+    click.echo("      }")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("virtual - Override in Subclass:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  class Animal {")
+    click.echo("      virtual void speak() {")
+    click.echo("          printl(\"...\");")
+    click.echo("      }")
+    click.echo("  }")
+    click.echo()
+    click.echo("  class Dog : extends Animal {")
+    click.echo("      void speak() {")
+    click.echo("          printl(\"Woof!\");")
+    click.echo("      }")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("abstract - Must Override:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  abstract class Shape {")
+    click.echo("      abstract float area();  // Must implement")
+    click.echo("  }")
+    click.echo()
+    click.echo("  class Circle : extends Shape {")
+    click.echo("      float radius;")
+    click.echo("      float area() {")
+    click.echo("          return 3.14 * this->radius * this->radius;")
+    click.echo("      }")
+    click.echo("  }")
+    click.echo()
+
+    click.secho("readonly - Read After Init:", fg='cyan')
+    click.echo("-" * 40)
+    click.echo("  class Config {")
+    click.echo("      readonly string path;")
+    click.echo()
+    click.echo("      constr Config(string p) {")
+    click.echo("          this->path = p;  // OK in constructor")
+    click.echo("      }")
+    click.echo("  }")
+    click.echo("  // cfg->path = \"x\";  // Error after construction")
+
+
+def _show_doc_builtins():
+    """Show built-in functions documentation."""
+    click.secho("Built-in Functions", fg='green', bold=True)
+    click.secho("=" * 60, fg='green')
+    click.echo()
+
+    click.secho("Output:", fg='cyan')
+    click.echo("  print(x)         - Print without newline")
+    click.echo("  printl(x)        - Print with newline")
+    click.echo("  error(msg)       - Print error message")
+    click.echo("  warn(msg)        - Print warning")
+    click.echo("  debug(x)         - Debug print")
+    click.echo()
+
+    click.secho("Type Conversion:", fg='cyan')
+    click.echo("  str(x)           - Convert to string")
+    click.echo("  int(x)           - Convert to integer")
+    click.echo("  float(x)         - Convert to float")
+    click.echo("  bool(x)          - Convert to boolean")
+    click.echo("  list(x)          - Convert to list")
+    click.echo()
+
+    click.secho("String Functions:", fg='cyan')
+    click.echo("  len(s)           - Length of string/list")
+    click.echo("  upper(s)         - Uppercase")
+    click.echo("  lower(s)         - Lowercase")
+    click.echo("  trim(s)          - Remove whitespace")
+    click.echo("  split(s, d)      - Split by delimiter")
+    click.echo("  join(list, d)    - Join with delimiter")
+    click.echo("  replace(s,o,n)   - Replace occurrences")
+    click.echo("  substr(s,i,l)    - Substring")
+    click.echo("  contains(s,sub)  - Check if contains")
+    click.echo("  startswith(s,p)  - Check prefix")
+    click.echo("  endswith(s,p)    - Check suffix")
+    click.echo()
+
+    click.secho("Math:", fg='cyan')
+    click.echo("  abs(x)           - Absolute value")
+    click.echo("  min(a, b)        - Minimum")
+    click.echo("  max(a, b)        - Maximum")
+    click.echo("  floor(x)         - Round down")
+    click.echo("  ceil(x)          - Round up")
+    click.echo("  round(x)         - Round to nearest")
+    click.echo("  sqrt(x)          - Square root")
+    click.echo("  pow(x, y)        - Power")
+    click.echo("  random()         - Random 0-1")
+    click.echo("  randint(a, b)    - Random int in range")
+    click.echo()
+
+    click.secho("Collections:", fg='cyan')
+    click.echo("  len(x)           - Length")
+    click.echo("  append(l, x)     - Add to list")
+    click.echo("  pop(l)           - Remove last")
+    click.echo("  insert(l, i, x)  - Insert at index")
+    click.echo("  remove(l, x)     - Remove first occurrence")
+    click.echo("  sort(l)          - Sort list")
+    click.echo("  reverse(l)       - Reverse list")
+    click.echo("  range(a, b)      - Number range")
+    click.echo("  keys(m)          - Map keys")
+    click.echo("  values(m)        - Map values")
+    click.echo()
+
+    click.secho("JSON (json::):", fg='cyan')
+    click.echo("  json::parse(s)   - Parse JSON string")
+    click.echo("  json::stringify(x) - Convert to JSON")
+    click.echo("  json::load(path) - Load JSON file")
+    click.echo("  json::save(x,p)  - Save to JSON file")
+    click.echo()
+
+    click.secho("File I/O:", fg='cyan')
+    click.echo("  read(path)       - Read file contents")
+    click.echo("  write(path, s)   - Write to file")
+    click.echo("  append(path, s)  - Append to file")
+    click.echo("  exists(path)     - Check if file exists")
+    click.echo()
+
+    click.secho("Time:", fg='cyan')
+    click.echo("  now()            - Current timestamp")
+    click.echo("  timestamp()      - Formatted timestamp")
+    click.echo("  sleep(ms)        - Wait milliseconds")
+    click.echo()
+
+    click.secho("Type Checking:", fg='cyan')
+    click.echo("  type(x)          - Get type name")
+    click.echo("  isinstance(x,t)  - Check instance")
+    click.echo("  isstring(x)      - Is string?")
+    click.echo("  isint(x)         - Is integer?")
+    click.echo("  islist(x)        - Is list?")
+    click.echo("  isnull(x)        - Is null?")
+    click.echo("  iscallable(x)    - Is function?")
+
+
 @cssl.command(name='doc')
 @click.argument('search', required=False, default=None)
 @click.option('--list', '-l', 'list_sections', is_flag=True, help='List all documentation sections')
-def cssl_doc(search, list_sections):
+@click.option('--get', '-g', 'show_categories', is_flag=True, help='Show all syntax categories')
+@click.option('--snapshots', '--snapshot', '-s', 'cat_snapshots', is_flag=True, help='Show % snapshot syntax')
+@click.option('--references', '--refs', '-r', 'cat_refs', is_flag=True, help='Show & reference syntax')
+@click.option('--overrides', '--override', '-o', 'cat_overrides', is_flag=True, help='Show ++, embedded, &<> override syntax')
+@click.option('--datatypes', '--types', '-t', 'cat_types', is_flag=True, help='Show all data types')
+@click.option('--keywords', '-k', 'cat_keywords', is_flag=True, help='Show all keywords')
+@click.option('--operators', '--ops', 'cat_operators', is_flag=True, help='Show all operators')
+@click.option('--containers', '-c', 'cat_containers', is_flag=True, help='Show container types (stack, vector, map)')
+@click.option('--globals', 'cat_globals', is_flag=True, help='Show @, global syntax')
+@click.option('--injection', '--inject', '-i', 'cat_injection', is_flag=True, help='Show <==, <<==, +<== injection syntax')
+@click.option('--open', 'cat_open', is_flag=True, help='Show open parameters and OpenFind')
+@click.option('--embedded', '-e', 'cat_embedded', is_flag=True, help='Show embedded function/class replacement')
+@click.option('--classes', 'cat_classes', is_flag=True, help='Show class, extends, overwrites syntax')
+@click.option('--enums', 'cat_enums', is_flag=True, help='Show enum definitions and EnumName::Value')
+@click.option('--exceptions', '--except', '-x', 'cat_exceptions', is_flag=True, help='Show try/catch/except/throw')
+@click.option('--modifiers', '-m', 'cat_modifiers', is_flag=True, help='Show const, private, static, etc.')
+@click.option('--builtins', '-b', 'cat_builtins', is_flag=True, help='Show built-in functions')
+def cssl_doc(search, list_sections, show_categories, cat_snapshots, cat_refs, cat_overrides,
+             cat_types, cat_keywords, cat_operators, cat_containers, cat_globals,
+             cat_injection, cat_open, cat_embedded, cat_classes, cat_enums, cat_exceptions,
+             cat_modifiers, cat_builtins):
     """Show CSSL documentation.
 
     \b
     Usage:
       includecpp cssl doc              # Show full documentation
       includecpp cssl doc "open"       # Search for 'open' keyword
-      includecpp cssl doc "$"          # Search for shared variable syntax
-      includecpp cssl doc "define"     # Search for define keyword
+      includecpp cssl doc --get        # Show syntax categories overview
+      includecpp cssl doc --snapshots  # Show % snapshot documentation
+      includecpp cssl doc --embedded   # Show embedded replacement docs
       includecpp cssl doc --list       # List all sections
 
     \b
-    Examples:
-      includecpp cssl doc "class"      # Show OOP/class documentation
-      includecpp cssl doc "json::"     # Show JSON functions
-      includecpp cssl doc "this->"     # Show this-> keyword usage
-      includecpp cssl doc "map"        # Show Map container docs
+    Categories:
+      --get, -g          Overview of all syntax categories
+      --snapshots, -s    % captured variable snapshots
+      --references, -r   & function/variable references
+      --overrides, -o    ++, embedded, &<> override syntax
+      --datatypes, -t    Data types (string, int, float, bool, ...)
+      --keywords, -k     All CSSL keywords
+      --operators        All operators (+, -, *, /, <==, <<==, ...)
+      --containers, -c   Container types (stack, vector, map, ...)
+      --globals          @ global variables
+      --injection, -i    Code injection (<==, <<==, +<==)
+      --open             open parameters and OpenFind
+      --embedded, -e     embedded function/class replacement
+      --classes          class, extends, overwrites, constr
+      --enums            enum definitions and EnumName::Value
+      --exceptions, -x   try/catch/except/throw/finally
+      --modifiers, -m    const, private, static, virtual, etc.
+      --builtins, -b     Built-in functions (printl, len, json::, ...)
     """
     from pathlib import Path as PathLib
     import os
@@ -7792,6 +8914,75 @@ def cssl_doc(search, list_sections):
             click.echo("Use: includecpp cssl doc \"<keyword>\" to search")
             return
 
+        # Category documentation mode
+        if show_categories:
+            _show_doc_categories()
+            return
+
+        if cat_snapshots:
+            _show_doc_snapshots()
+            return
+
+        if cat_refs:
+            _show_doc_references()
+            return
+
+        if cat_overrides:
+            _show_doc_overrides()
+            return
+
+        if cat_types:
+            _show_doc_datatypes()
+            return
+
+        if cat_keywords:
+            _show_doc_keywords()
+            return
+
+        if cat_operators:
+            _show_doc_operators()
+            return
+
+        if cat_containers:
+            _show_doc_containers()
+            return
+
+        if cat_globals:
+            _show_doc_globals()
+            return
+
+        if cat_injection:
+            _show_doc_injection()
+            return
+
+        if cat_open:
+            _show_doc_open()
+            return
+
+        if cat_embedded:
+            _show_doc_embedded()
+            return
+
+        if cat_classes:
+            _show_doc_classes()
+            return
+
+        if cat_enums:
+            _show_doc_enums()
+            return
+
+        if cat_exceptions:
+            _show_doc_exceptions()
+            return
+
+        if cat_modifiers:
+            _show_doc_modifiers()
+            return
+
+        if cat_builtins:
+            _show_doc_builtins()
+            return
+
         # Search mode
         if search:
             click.secho(f"Searching for: '{search}'", fg='cyan', bold=True)
@@ -7799,23 +8990,25 @@ def cssl_doc(search, list_sections):
             click.echo()
 
             # Split into subsections (### headers) for focused results
-            subsections = re.split(r'(?=^### )', content, flags=re.MULTILINE)
+            # Note: Allow optional leading whitespace since doc may be indented
+            subsections = re.split(r'(?=^\s*### )', content, flags=re.MULTILINE)
 
             # Also split into main sections (## headers)
-            main_sections = re.split(r'(?=^## )', content, flags=re.MULTILINE)
+            main_sections = re.split(r'(?=^\s*## )', content, flags=re.MULTILINE)
 
             # Find matching subsections (### level) - most focused
             matching_subsections = []
             for subsection in subsections:
                 if search.lower() in subsection.lower():
-                    # Extract title
-                    title_match = re.match(r'^###\s+(.+)$', subsection, re.MULTILINE)
+                    # Extract title (allow leading whitespace)
+                    title_match = re.match(r'^\s*###\s+(.+)$', subsection, re.MULTILINE)
                     if title_match:
                         # Trim subsection to just the content until next ### or ##
                         lines = subsection.split('\n')
                         trimmed_lines = []
                         for line in lines:
-                            if line.startswith('## ') and not line.startswith('### '):
+                            stripped = line.lstrip()
+                            if stripped.startswith('## ') and not stripped.startswith('### '):
                                 break
                             trimmed_lines.append(line)
                         matching_subsections.append((title_match.group(1), '\n'.join(trimmed_lines)))
@@ -7853,7 +9046,7 @@ def cssl_doc(search, list_sections):
                 found_sections = []
                 for section in main_sections:
                     if search.lower() in section.lower():
-                        title_match = re.match(r'^##\s+(.+)$', section, re.MULTILINE)
+                        title_match = re.match(r'^\s*##\s+(.+)$', section, re.MULTILINE)
                         if title_match:
                             found_sections.append((title_match.group(1), section))