laddercodec 0.2.1__tar.gz → 0.2.2__tar.gz

laddercodec-0.2.2/.github/scripts/check_public_site.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Reject private sources and incomplete generated docs in the public site."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+BLOCKED_FILENAMES = {
+    "agents",
+    "agents.html",
+    "agents.md",
+    "claude",
+    "claude.html",
+    "claude.md",
+    "gen_llms.py",
+    "gen_reference.py",
+    "llms-full.txt",
+}
+BLOCKED_PATH_PARTS = {"__pycache__", "agents", "claude"}
+EXPECTED_FILES = {
+    "index.html",
+    "llms.txt",
+    "reference/index.html",
+    "reference/api/codec/index.html",
+    "reference/api/csv/index.html",
+    "reference/api/instructions/index.html",
+}
+
+
+def ascii_text(value: object) -> str:
+    return str(value).encode("ascii", errors="backslashreplace").decode("ascii")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Check generated public-site paths.")
+    parser.add_argument("site", type=Path, help="Generated site directory to inspect")
+    args = parser.parse_args()
+
+    site = args.site
+    if not site.is_dir():
+        print(f"ERROR: public site directory does not exist: {ascii_text(site)}")
+        return 2
+
+    violations: list[str] = []
+    actual_files = {
+        path.relative_to(site).as_posix()
+        for path in site.rglob("*")
+        if path.is_file()
+    }
+    for relative_path in actual_files:
+        path = Path(relative_path)
+        if path.name.lower() in BLOCKED_FILENAMES or any(
+            part.lower() in BLOCKED_PATH_PARTS for part in path.parts
+        ):
+            violations.append(f"blocked public-site path: {relative_path}")
+
+    for missing in sorted(EXPECTED_FILES - actual_files):
+        violations.append(f"missing expected public-site path: {missing}")
+
+    for path in site.rglob("*"):
+        if path.suffix.lower() not in {".html", ".md", ".txt"} or not path.is_file():
+            continue
+        if "::: laddercodec." in path.read_text(encoding="utf-8", errors="replace"):
+            relative_path = path.relative_to(site).as_posix()
+            violations.append(f"unrendered API directive: {relative_path}")
+
+    if violations:
+        for violation in sorted(violations):
+            print(f"ERROR: {ascii_text(violation)}")
+        print(f"ERROR: public-site guard found {len(violations)} violation(s).")
+        return 1
+
+    print(f"OK: public-site guard passed: {ascii_text(site)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

laddercodec-0.2.2/.github/scripts/prune_public_site.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Remove explicitly private source files copied by Zensical 0.0.57."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+from pathlib import Path
+
+
+PRIVATE_ROOT_NAMES = {
+    "__pycache__",
+    "agents",
+    "agents.md",
+    "claude",
+    "claude.md",
+    "gen_llms.py",
+    "gen_reference.py",
+}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Prune private public-site paths.")
+    parser.add_argument("site", type=Path, help="Generated site directory to prune")
+    args = parser.parse_args()
+
+    site = args.site.resolve()
+    if not site.is_dir():
+        raise RuntimeError(f"Public site directory does not exist: {site}")
+
+    for path in site.iterdir():
+        if path.name.lower() not in PRIVATE_ROOT_NAMES:
+            continue
+        resolved = path.resolve()
+        if resolved.parent != site:
+            raise RuntimeError(f"Refusing to prune path outside public site: {resolved}")
+        if resolved.is_dir():
+            shutil.rmtree(resolved)
+        else:
+            resolved.unlink()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{laddercodec-0.2.1 → laddercodec-0.2.2}/.github/workflows/docs.yml

@@ -3,6 +3,8 @@ name: Docs
 on:
   push:
     branches: ["main"]
+  pull_request:
+    branches: ["main"]
   workflow_dispatch:
 
 permissions:
@@ -34,17 +36,25 @@ jobs:
       - name: Install docs dependencies
         run: uv sync --locked --group docs
 
+      - name: Cache-bust extra assets
+        run: |
+          sed -i -E "s#^(\s*- (stylesheets|javascripts)/[^?[:space:]]+)\$#\1?v=${GITHUB_SHA::8}#" mkdocs.yml
+          grep -E '\?v=' mkdocs.yml
+
       - name: Build docs
-        run: uv run mkdocs build --strict
-        env:
-          DISABLE_MKDOCS_2_WARNING: "true"
+        run: make docs-check
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
 
       - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
         uses: actions/upload-pages-artifact@v4
         with:
           path: site
 
   deploy:
+    if: github.event_name != 'pull_request'
     needs: build
     runs-on: ubuntu-latest
     environment:

{laddercodec-0.2.1 → laddercodec-0.2.2}/.gitignore

@@ -27,4 +27,5 @@ htmlcov/
 
 # Docs
 site/
+docs/reference/
 

{laddercodec-0.2.1 → laddercodec-0.2.2}/AGENTS.md

@@ -115,7 +115,7 @@ tests/
     └── tumbler/                 # 34 real programs: <name>.scr + <name>.clipboard.{bin,csv}
 ```
 
-Golden fixtures verified through Click paste round-trip. The tumbler fixture pairs each Click internal program file (`.scr`) with a clipboard capture of the same program; `devtools/compare_csv.py <dir>` compares `<name>.csv` (scr decode) against `<name>.clipboard.csv` ground truth.
+Ladder golden fixtures are verified through Click paste round-trip. In `scr_captures`, `time_drums.bin` is synthetic (see that directory's README); do not use its differences from SCR as evidence of native cleanup. The tumbler fixture pairs each Click internal program file (`.scr`) with a clipboard capture of the same program; `devtools/compare_csv.py <dir>` compares `<name>.csv` (scr decode) against `<name>.clipboard.csv` ground truth.
 
 ## Binary Format
 
@@ -127,7 +127,7 @@ Quick reference: three regions — program header (0x0254), payload region (0x02
 
 Full spec: [`docs/internals/wire-rendering.md`](docs/internals/wire-rendering.md) — flag bytes, left-edge rendering, segment flag boundary rules.
 
-Quick reference: three flag bytes per cell — segment (+0x19), right (+0x1D), down (+0x21). Wire tokens classified by (right, down) only. Segment flag boundary computed per-row. Row 0 exempt.
+Quick reference: three flag bytes per cell — segment (+0x19), right (+0x1D), down (+0x21). Wire tokens classified by (right, down) only. Segment flag boundary computed per-row. The encoder treats row 0 as exempt; native segment flags retain editing history.
 
 ## Instruction Blobs
 
@@ -160,7 +160,7 @@ All tested shapes pass Click round-trip (verified via paste → copy-back):
 
 The clipboard decoder (`decode.py`) reads Click clipboard binaries back into structured data. Validated against a 37-rung native capture covering all basic instruction types.
 
-The program file decoder (`decode_program.py`) reads Click's internal `Scr*.tmp` files. Returns a `Program` with name, index, and all rungs. Validated against the 114-rung coverage fixture, shift/counter/drum programs, and the 34-program tumbler fixture (byte-identical CSV vs clipboard captures). Row topology uses the uniform row-block framing documented in `docs/internals/binary-format.md` §"SCR row-topology blocks".
+The program file decoder (`decode_program.py`) reads Click's internal `Scr*.tmp` files. Returns a `Program` with name, index, and all rungs. Validated against the 114-rung coverage fixture, shift/counter/drum programs, and the 34-program tumbler fixture (byte-identical CSV vs clipboard captures). SCR headers use counted numeric widths and independent display flags. Every counted topology row, including the special first row, is parsed without recovery; ordinary stored wire rows are preserved. Row topology uses the uniform row-block framing documented in `docs/internals/binary-format.md` §"SCR row-topology blocks".
 
 **All standard Click instruction types decoded natively:**
 - Contacts: NO, NC, edge (rise/fall), immediate (NO/NC)

{laddercodec-0.2.1 → laddercodec-0.2.2}/CHANGELOG.md

@@ -8,7 +8,19 @@
      Review and condense before release — entries accumulate during development and
      should be edited into shape before moving from Unreleased to a version heading. -->
 
-## 0.2.1 (Unreleased)
+## 0.2.2 (2026-09-10)
+
+### Fixed
+- **SCR decode**: parse counted column widths, independent display flags, and all stored rows so valid populated special rows no longer trigger recovery, and malformed records fail without silently skipping a rung.
+- **SCR decode**: preserve branch wiring above a later rail-connected row instead of deleting the branch and shifting the lower wire upward.
+
+### Added
+- **Native drum regression fixtures**: preserve the original NOP's wire row and a branch above it after row insertion and drum placement, with native SCR/clipboard and CSV comparisons.
+
+### Documentation
+- Correct SCR flag meanings and fixture provenance, and distinguish native persisted flags from the encoder's construction conventions.
+
+## 0.2.1 (2026-08-25)
 
 ### Fixed
 - **SCR decode**: a Modbus `Send` at `device_id=0` no longer decodes as `device_id=1` — SCR blobs elide fields at their class default, and Send's device_id default (0) differs from Receive's (1).
@@ -23,7 +35,7 @@
 ### Fixed
 - **SCR decode**: correct the row-topology block framing — every row (including row 0) uses one uniform block format, fixing branch rungs whose wires (`T`/`|`/`-`) were silently dropped whenever a continuation row's first right-wired cell carried segment flag 1.
 - **SCR decode**: accept placement-ordered flag-table entries — native captures store columns out of order (e.g. `[6,1,0,3,2,4,5]`), which the old sorted-order validation rejected.
-- **SCR decode**: drop orphaned editor-debris wire rows stored above a rung's true row 0 (observed under drum boxes), matching what Click's own clipboard copy produces.
+- **SCR decode**: introduced deletion of presumed orphan wire rows above a later rail-connected row; the claimed native clipboard agreement was based on a synthetic fixture, and this behavior is reversed in 0.2.2.
 
 ### Changed
 - **SCR decode**: replace the heuristic topology parser (leading-row guessing, count_down special cases, end-marker scanning) with a deterministic parser derived from the verified format — see `docs/internals/binary-format.md` §"SCR row-topology blocks" for the spec.

{laddercodec-0.2.1 → laddercodec-0.2.2}/Makefile

@@ -3,7 +3,7 @@
 
 .DEFAULT_GOAL := default
 
-.PHONY: default install lint test golden coverage-golden upgrade build clean docs-serve docs-build docs-check
+.PHONY: default install lint test golden coverage-golden upgrade build clean docs-generate docs-serve docs-build docs-check
 
 default: install lint test
 
@@ -29,11 +29,17 @@ upgrade:
 build:
 	uv build
 
-docs-serve:
-	DISABLE_MKDOCS_2_WARNING=true uv run --group docs mkdocs serve
+docs-generate:
+	uv run --group docs python docs/gen_reference.py
 
-docs-build:
-	DISABLE_MKDOCS_2_WARNING=true uv run --group docs mkdocs build --strict
+docs-serve: docs-generate
+	uv run --group docs zensical serve
+
+docs-build: docs-generate
+	uv run --group docs zensical build --clean --strict
+	uv run --group docs python .github/scripts/prune_public_site.py site
+	uv run --group docs python docs/gen_llms.py site
+	uv run --group docs python .github/scripts/check_public_site.py site
 
 docs-check: docs-build
 

laddercodec-0.2.2/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: laddercodec
+Version: 0.2.2
+Summary: Binary codec for AutomationDirect CLICK PLC ladder clipboard format
+Project-URL: Repository, https://github.com/ssweber/laddercodec
+Project-URL: Documentation, https://pyrung.com/laddercodec/
+Author-email: ssweber <57631333+ssweber@users.noreply.github.com>
+License-Expression: MPL-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.11
+Description-Content-Type: text/markdown
+
+# laddercodec
+
+**The compatibility layer for CLICK ladder data.** laddercodec reads and writes CLICK's native representations and enables reliable round-tripping between CLICK and the pyrung/ClickNick toolchain. Tested against v2.60 to v3.9x captures. Zero runtime dependencies.
+
+It's the layer [ClickNick](https://pyrung.com/clicknick/) pastes through, and it's useful on its own to convert between CLICK ladder data, Python objects, and CSV.
+
+- Documentation: https://pyrung.com/laddercodec/
+- LLM docs index: https://pyrung.com/laddercodec/llms.txt
+- LLM full context: https://pyrung.com/laddercodec/llms-full.txt
+
+## Install
+
+```bash
+uv add laddercodec
+# or
+pip install laddercodec
+```
+
+Requires Python 3.11+.
+
+## Quick example
+
+```python
+from laddercodec import read_csv, encode, decode
+
+# CSV → binary (ready to paste into Click)
+rungs = read_csv("my_rung.csv")
+binary = encode(rungs[0])
+
+# Binary → structured data
+rung = decode(binary)
+print(rung.logical_rows)
+print(rung.instructions)
+```
+
+## What's included
+
+**[Encoder](https://pyrung.com/laddercodec/guides/encoding/)** — `encode()` takes `Rung` objects or canonical CSV and produces clipboard binary ready to paste into Click. Supports all standard instruction types, wire topologies, and styled comments.
+
+**[Decoder](https://pyrung.com/laddercodec/guides/decoding/)** — `decode()` reads clipboard binary back into structured Python objects (contacts, coils, timers, wires, comments). `decode_program()` reads ladder data from native CLICK program files.
+
+**[CSV I/O](https://pyrung.com/laddercodec/guides/csv-format/)** — `read_csv()` and `write_csv()` convert between the 33-column canonical CSV format and `Rung` objects. Multi-file program bundles supported.
+
+**[CLICK format reference](https://pyrung.com/laddercodec/internals/binary-format/)** — Technical reference for CLICK's native clipboard and program representations, including binary layouts and instruction records.
+
+## Status
+
+`laddercodec` is **beta** for clipboard encode/decode, CSV I/O, and `decode_program()`.
+
+`Email`, `Home`, `Position`, and `Velocity` still intentionally surface as `raw(...)` passthroughs so clipboard and program data round-trips stay lossless while those families remain opaque.
+
+## Learn more
+
+| | |
+|---|---|
+| [Encoding guide](https://pyrung.com/laddercodec/guides/encoding/) | Encode, decode, and round-trip your first rung |
+| [Decoding guide](https://pyrung.com/laddercodec/guides/decoding/) | Structured decode, program files, round-trip identity |
+| [CSV format](https://pyrung.com/laddercodec/guides/csv-format/) | 33-column canonical format, bundle layout, topology rules |
+| [Adding instructions](https://pyrung.com/laddercodec/guides/adding-instructions/) | Extend the codec with new instruction types |
+| [API reference](https://pyrung.com/laddercodec/reference/) | Auto-generated from docstrings |
+
+## Development
+
+```bash
+make install        # uv sync --all-extras --dev
+make test           # pytest
+make lint           # ruff + ty
+make golden         # regenerate .bin from .csv fixtures
+make docs-serve     # local docs dev server
+make                # all of the above
+```
+
+## License
+
+[MPL-2.0](LICENSE)

laddercodec-0.2.2/README.md

@@ -0,0 +1,75 @@
+# laddercodec
+
+**The compatibility layer for CLICK ladder data.** laddercodec reads and writes CLICK's native representations and enables reliable round-tripping between CLICK and the pyrung/ClickNick toolchain. Tested against v2.60 to v3.9x captures. Zero runtime dependencies.
+
+It's the layer [ClickNick](https://pyrung.com/clicknick/) pastes through, and it's useful on its own to convert between CLICK ladder data, Python objects, and CSV.
+
+- Documentation: https://pyrung.com/laddercodec/
+- LLM docs index: https://pyrung.com/laddercodec/llms.txt
+- LLM full context: https://pyrung.com/laddercodec/llms-full.txt
+
+## Install
+
+```bash
+uv add laddercodec
+# or
+pip install laddercodec
+```
+
+Requires Python 3.11+.
+
+## Quick example
+
+```python
+from laddercodec import read_csv, encode, decode
+
+# CSV → binary (ready to paste into Click)
+rungs = read_csv("my_rung.csv")
+binary = encode(rungs[0])
+
+# Binary → structured data
+rung = decode(binary)
+print(rung.logical_rows)
+print(rung.instructions)
+```
+
+## What's included
+
+**[Encoder](https://pyrung.com/laddercodec/guides/encoding/)** — `encode()` takes `Rung` objects or canonical CSV and produces clipboard binary ready to paste into Click. Supports all standard instruction types, wire topologies, and styled comments.
+
+**[Decoder](https://pyrung.com/laddercodec/guides/decoding/)** — `decode()` reads clipboard binary back into structured Python objects (contacts, coils, timers, wires, comments). `decode_program()` reads ladder data from native CLICK program files.
+
+**[CSV I/O](https://pyrung.com/laddercodec/guides/csv-format/)** — `read_csv()` and `write_csv()` convert between the 33-column canonical CSV format and `Rung` objects. Multi-file program bundles supported.
+
+**[CLICK format reference](https://pyrung.com/laddercodec/internals/binary-format/)** — Technical reference for CLICK's native clipboard and program representations, including binary layouts and instruction records.
+
+## Status
+
+`laddercodec` is **beta** for clipboard encode/decode, CSV I/O, and `decode_program()`.
+
+`Email`, `Home`, `Position`, and `Velocity` still intentionally surface as `raw(...)` passthroughs so clipboard and program data round-trips stay lossless while those families remain opaque.
+
+## Learn more
+
+| | |
+|---|---|
+| [Encoding guide](https://pyrung.com/laddercodec/guides/encoding/) | Encode, decode, and round-trip your first rung |
+| [Decoding guide](https://pyrung.com/laddercodec/guides/decoding/) | Structured decode, program files, round-trip identity |
+| [CSV format](https://pyrung.com/laddercodec/guides/csv-format/) | 33-column canonical format, bundle layout, topology rules |
+| [Adding instructions](https://pyrung.com/laddercodec/guides/adding-instructions/) | Extend the codec with new instruction types |
+| [API reference](https://pyrung.com/laddercodec/reference/) | Auto-generated from docstrings |
+
+## Development
+
+```bash
+make install        # uv sync --all-extras --dev
+make test           # pytest
+make lint           # ruff + ty
+make golden         # regenerate .bin from .csv fixtures
+make docs-serve     # local docs dev server
+make                # all of the above
+```
+
+## License
+
+[MPL-2.0](LICENSE)

laddercodec-0.2.2/docs/gen_llms.py

@@ -0,0 +1,95 @@
+"""Generate a concise llms.txt index for the rendered Zensical site."""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+from collections.abc import Iterator, Sequence
+from pathlib import Path, PurePosixPath
+from urllib.parse import urljoin
+
+import yaml
+
+
+ROOT = Path(__file__).resolve().parent.parent
+CONFIG_PATH = ROOT / "mkdocs.yml"
+DOCS_DIR = ROOT / "docs"
+
+
+def _navigation_titles(nav: list[object]) -> dict[str, str]:
+    titles: dict[str, str] = {}
+
+    def visit(items: Sequence[object]) -> None:
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            for title, target in item.items():
+                if isinstance(target, str):
+                    titles[target] = str(title)
+                elif isinstance(target, list):
+                    visit(target)
+
+    visit(nav)
+    return titles
+
+
+def _source_uris(pattern: str) -> Iterator[str]:
+    candidates = sorted(
+        path.relative_to(DOCS_DIR).as_posix() for path in DOCS_DIR.rglob("*.md")
+    )
+    yield from fnmatch.filter(candidates, pattern)
+
+
+def _destination_uri(source_uri: str) -> str:
+    source = PurePosixPath(source_uri)
+    if source.name == "index.md":
+        parent = source.parent.as_posix()
+    else:
+        parent = source.with_suffix("").as_posix()
+    return "" if parent == "." else f"{parent}/"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate the LLM documentation index.")
+    parser.add_argument("site", type=Path, help="Rendered Zensical site directory")
+    args = parser.parse_args()
+
+    config = yaml.safe_load(CONFIG_PATH.read_text(encoding="utf-8"))
+    site_dir = args.site.resolve()
+    if not site_dir.is_dir():
+        raise RuntimeError(f"Rendered site directory does not exist: {site_dir}")
+
+    base_url = config["site_url"]
+    if not base_url.endswith("/"):
+        base_url += "/"
+    titles = _navigation_titles(config["nav"])
+
+    output = f"# {config['site_name']}\n\n"
+    if description := config.get("site_description"):
+        output += f"> {description}\n\n"
+
+    seen: set[str] = set()
+    for section, patterns in config["extra"]["llmstxt"]["sections"].items():
+        output += f"## {section}\n\n"
+        for pattern in patterns:
+            matches = list(_source_uris(pattern)) if "*" in pattern else [pattern]
+            for source_uri in matches:
+                if source_uri in seen:
+                    continue
+                seen.add(source_uri)
+                title = titles.get(source_uri)
+                if title is None:
+                    raise RuntimeError(f"Navigation title not found for {source_uri}")
+                destination_uri = _destination_uri(source_uri)
+                html_path = site_dir / Path(destination_uri) / "index.html"
+                if not html_path.is_file():
+                    raise RuntimeError(f"Rendered page not found: {html_path}")
+                output += f"- [{title}]({urljoin(base_url, destination_uri)})\n"
+        output += "\n"
+
+    (site_dir / "llms.txt").write_text(output, encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{laddercodec-0.2.1 → laddercodec-0.2.2}/docs/gen_reference.py

@@ -1,4 +1,4 @@
-"""Generate curated MkDocs API reference pages for laddercodec public exports."""
+"""Generate curated API reference pages for laddercodec public exports."""
 
 from __future__ import annotations
 
@@ -7,9 +7,8 @@ from dataclasses import dataclass
 from importlib import import_module
 from pathlib import Path
 
-import mkdocs_gen_files
-
 PACKAGE = "laddercodec"
+DOCS_DIR = Path(__file__).parent
 
 
 @dataclass(frozen=True)
@@ -109,9 +108,9 @@ def _write_reference_page(page: ReferencePage) -> None:
         lines.append(f"::: {PACKAGE}.{symbol}")
         lines.append("")
 
-    with mkdocs_gen_files.open(doc_rel_path, "w") as fd:
-        fd.write("\n".join(lines).rstrip() + "\n")
-    mkdocs_gen_files.set_edit_path(doc_rel_path, Path("docs/gen_reference.py"))
+    destination = DOCS_DIR / doc_rel_path
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
 
 
 def _write_index() -> None:
@@ -133,9 +132,9 @@ def _write_index() -> None:
         for page in advanced_pages:
             lines.append(f"- [{page.title}](api/{page.slug}.md)")
 
-    with mkdocs_gen_files.open("reference/index.md", "w") as fd:
-        fd.write("\n".join(lines).rstrip() + "\n")
-    mkdocs_gen_files.set_edit_path("reference/index.md", Path("docs/gen_reference.py"))
+    destination = DOCS_DIR / "reference/index.md"
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
 
 
 _validate_manifest()

{laddercodec-0.2.1 → laddercodec-0.2.2}/docs/guides/csv-format.md

@@ -115,7 +115,7 @@ No explicit `+` topology token is emitted.
 
 ## Vertical topology
 
-OR conditions (`any_of`), multi-output stacking, and `branch()` conditions all
+OR conditions (`Or()`), multi-output stacking, and `branch()` conditions all
 use continuation rows within a rung. These mechanisms share the same vertical
 space - OR branch rows double as multi-output and branch rows.
 
@@ -173,11 +173,11 @@ merge/split columns even when their own column has no marker below.
   conditions. Shared AND-prefix contacts from earlier columns are not repeated.
 - Each continuation row has at most one AF token or is blank in AF.
 
-## `any_of(...)` OR expansion
+## `Or(...)` expansion
 
 ### Simple OR at power rail
 
-`any_of(X001, X002, X003)`:
+`Or(X001, X002, X003)`:
 
 ```text
      A      B     ...   AF
@@ -191,7 +191,7 @@ blank.
 
 ### Mid-rung OR
 
-`X001, any_of(X002, C1)`:
+`X001, Or(X002, C1)`:
 
 ```text
      A      B       C     ...   AF
@@ -204,7 +204,7 @@ blank. Shared AND-prefix (`X001`) appears only on the first row.
 
 ### Series ORs
 
-`any_of(X001, X002), any_of(C1, C2)`:
+`Or(X001, X002), Or(C1, C2)`:
 
 ```text
      A      B     C      D     ...   AF
@@ -261,7 +261,7 @@ When a rung has both OR conditions and multiple outputs/branches, they share the
 same set of continuation rows. The OR branches provide the rows needed for the
 outputs.
 
-`X001, any_of(X002, X003, X004)` -> `out(Y001)`, `branch(C1): out(Y002)`,
+`X001, Or(X002, X003, X004)` -> `out(Y001)`, `branch(C1): out(Y002)`,
 `out(Y003)`:
 
 ```text

{laddercodec-0.2.1 → laddercodec-0.2.2}/docs/guides/troubleshooting.md

@@ -70,7 +70,7 @@ The cell header is 0x25 (37) bytes. Key fields:
 | +0x09 | row_span | How many grid rows this cell occupies |
 | +0x0A | visual_rows | Visual sub-row count (1 = normal, 2 = timer, 3 = retained timer) |
 | +0x0D | instr_index | 4-byte LE signed. `-1` (0xFFFFFFFF) for data cells |
-| +0x15 | contact_flag | 4-byte LE |
+| +0x15 | row_start_flag (column A) | 4-byte LE |
 | +0x19 | segment | 4-byte LE — load-bearing flag |
 | +0x1D | wire_right | 4-byte LE |
 | +0x21 | wire_down | 4-byte LE |

{laddercodec-0.2.1 → laddercodec-0.2.2}/docs/index.md

@@ -1,6 +1,8 @@
 # laddercodec
 
-**Binary codec for AutomationDirect CLICK PLC ladder clipboard format.** Encodes and decodes the native clipboard binary used by [CLICK Programming Software](https://www.automationdirect.com/clickplcs). Tested against v2.60-v3.9x captures. Zero runtime dependencies.
+**The compatibility layer for CLICK ladder data.** laddercodec reads and writes CLICK's native representations and enables reliable round-tripping between CLICK and the pyrung/ClickNick toolchain. Tested against v2.60 to v3.9x captures. Zero runtime dependencies.
+
+It's the layer [ClickNick](https://pyrung.com/clicknick/) pastes through, and it's useful on its own to convert between CLICK ladder data, Python objects, and CSV.
 
 ## Install
 
@@ -31,17 +33,17 @@ print(rung.instructions)
 
 **[Encoder](guides/encoding.md)** — `encode()` takes `Rung` objects or canonical CSV and produces clipboard binary ready to paste into Click. Supports all standard instruction types, wire topologies, and styled comments.
 
-**[Decoder](guides/decoding.md)** — `decode()` reads clipboard binary back into structured Python objects (contacts, coils, timers, wires, comments). `decode_program()` reads Click's internal `Scr*.tmp` program files.
+**[Decoder](guides/decoding.md)** — `decode()` reads clipboard binary back into structured Python objects (contacts, coils, timers, wires, comments). `decode_program()` reads ladder data from native CLICK program files.
 
 **[CSV I/O](guides/csv-format.md)** — `read_csv()` and `write_csv()` convert between the 33-column canonical CSV format and `Rung` objects. Multi-file program bundles supported.
 
-**[Binary format docs](internals/binary-format.md)** — Byte-level reverse engineering of Click's clipboard and program file formats: buffer layout, cell grid, wire flags, instruction blobs, and multi-rung framing.
+**[CLICK format reference](internals/binary-format.md)** — Technical reference for CLICK's native clipboard and program representations, including binary layouts and instruction records.
 
 ## Status
 
 `laddercodec` is **beta** for clipboard encode/decode, CSV I/O, and `decode_program()`.
 
-`Email`, `Home`, `Position`, and `Velocity` still intentionally surface as `raw(...)` passthroughs so binary and SCR round-trips stay lossless while those families remain opaque.
+`Email`, `Home`, `Position`, and `Velocity` still intentionally surface as `raw(...)` passthroughs so clipboard and program data round-trips stay lossless while those families remain opaque.
 
 ## Guide overview