surf-cli 0.7.0__tar.gz → 0.7.1__tar.gz

{surf_cli-0.7.0 → surf_cli-0.7.1}/.agents/skills/surf/SKILL.md

@@ -8,7 +8,7 @@ metadata:
     github_username: saintx
     email: alex@saintx.us
     twitter: alexsaintx
-  surf-version: "0.7.0"
+  surf-version: "0.7.1"
 ---
 
 # Surf: Progressive Context Disclosure
@@ -42,19 +42,11 @@ Resolve with `surf` against the section heading; do not bulk-ingest a whole refe
 | Platform aggregation (batch section extraction) | `surf references/usage.md "Platform aggregation (batch section extraction)"` |
 | Additional options | `surf references/usage.md "Additional options"` |
 
-### Whitepaper (TeX and PDF examples)
+### TeX and PDF
 
-The same paper ships as `references/surf.tex` and `references/surf.pdf`; both list the same tree, so any row below works against either file.
+`references/surf.tex` and `references/surf.pdf` are one document in two forms. The same address works on either.
 
 | Intent | Section extraction |
 |--------|--------------------|
-| List a TeX paper's sections | `surf references/surf.tex --list` |
-| List a PDF's outline | `surf references/surf.pdf --list` |
-| Read the abstract | `surf references/surf.tex "abstract"` |
-| Why surf exists | `surf references/surf.pdf "Background"` |
-| What a thin index looks like | `surf references/surf.tex "A Thin Index Shaped by Intent"` |
-| Who composes context | `surf references/surf.pdf "Agentic Context Composition"` |
-| Check a skill mechanically | `surf references/surf.tex "Skills You Can Check"` |
-| Compose indexes across skills | `surf references/surf.pdf "Indexes over Indexes"` |
-| Formats and corpora surf addresses | `surf references/surf.tex "Markdown, TeX, and PDF"` |
-| How the paper checks itself | `surf references/surf.pdf "This Paper"` |
+| Extract a section from TeX | `surf references/surf.tex "Markdown, TeX, and PDF"` |
+| Extract a section from PDF | `surf references/surf.pdf "Markdown, TeX, and PDF"` |

{surf_cli-0.7.0 → surf_cli-0.7.1}/.agents/skills/surf/references/about.md

@@ -5,7 +5,7 @@ metadata:
     github_username: saintx
     email: alex@saintx.us
     twitter: alexsaintx
-  surf-version: "0.7.0"
+  surf-version: "0.7.1"
 ---
 # Surf — About
 

{surf_cli-0.7.0 → surf_cli-0.7.1}/.agents/skills/surf/references/usage.md

@@ -5,7 +5,7 @@ metadata:
     github_username: saintx
     email: alex@saintx.us
     twitter: alexsaintx
-  surf-version: "0.7.0"
+  surf-version: "0.7.1"
 ---
 # Surf Usage
 

{surf_cli-0.7.0 → surf_cli-0.7.1}/.claude-plugin/marketplace.json

@@ -3,14 +3,14 @@
   "owner": { "name": "Alexander R. Saint Croix", "email": "alex@saintx.us" },
   "metadata": {
     "description": "Plugins shipped with the surf CLI.",
-    "version": "0.7.0"
+    "version": "0.7.1"
   },
   "plugins": [
     {
       "name": "surf",
       "source": "./plugins/surf",
       "description": "Extract a markdown heading, TeX section, or PDF outline item without loading the rest of the file.",
-      "version": "0.7.0",
+      "version": "0.7.1",
       "category": "tooling",
       "keywords": ["surf", "markdown", "tex", "pdf", "context", "skills"]
     }

surf_cli-0.7.1/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to surf
+
+How to get a working tree, run the tests, and pass lint. The release procedure is in [RELEASING.md](https://github.com/saintx/surf-cli/blob/main/RELEASING.md).
+
+## Environment
+
+Python 3.12+ and [uv](https://docs.astral.sh/uv/). Either of these gives a shell with the dev dependencies installed:
+
+```bash
+nix develop        # python312 + uv, then uv sync
+uv sync            # without Nix; the dev group is installed by default
+```
+
+Run the checkout's `surf` without installing it:
+
+```bash
+uv run surf --version
+```
+
+## Layout
+
+```
+src/surf/
+  models.py        data types
+  logic.py         heading trees, section extraction; pure, no I/O
+  adapters.py      file reading, TeX expansion, pypdf
+  orchestrator.py  CLI: argument parsing, dispatch, exit codes
+  test_*.py        tests, beside the modules they cover
+plugins/surf/      the agent skill and its manifests
+scripts/           test.sh, lint.sh, deploy.sh
+```
+
+The layers only depend downward, and `pypdf` is confined to `adapters.py`. Four `import-linter` contracts in `pyproject.toml` enforce this, and `scripts/lint.sh` runs them.
+
+## Tests
+
+```bash
+scripts/test.sh    # uv run pytest src/surf -q
+```
+
+Tests live in `src/surf/test_*.py` and are excluded from the wheel. The root `tests/` directory is unused.
+
+## Lint
+
+```bash
+scripts/lint.sh
+```
+
+Runs, in order: `isort`, `black` (line length 100), `autoflake` (unused imports), `pyright` (basic mode, unused imports are errors), and `lint-imports` against the layer contracts. The first three rewrite files in place; run it before committing.
+
+## Version
+
+`surf --version` must agree with the version in every location listed in [RELEASING.md](https://github.com/saintx/surf-cli/blob/main/RELEASING.md). Changes that are not a release do not bump it.

surf_cli-0.7.1/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.5
+Name: surf-cli
+Version: 0.7.1
+Summary: List headings, or extract one section by name, from Markdown, TeX, or PDF.
+Project-URL: Homepage, https://github.com/saintx/surf-cli
+Project-URL: Repository, https://github.com/saintx/surf-cli
+Project-URL: Issues, https://github.com/saintx/surf-cli/issues
+Project-URL: Author, https://github.com/saintx
+Author-email: "Alexander R. Saint Croix" <alex@saintx.us>
+License: MIT License
+        
+        Copyright (c) 2026 Alexander R. Saint Croix
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pypdf>=6.17.0
+Description-Content-Type: text/markdown
+
+# surf
+
+List headings, or extract one section by name, from Markdown, TeX, or PDF.
+
+Distribution `surf-cli`. Command `surf`. Python 3.12+; pypdf is the one runtime dependency, for PDF outlines. Only the section you name is printed, so the rest of the file never enters an agent's context.
+
+## Install
+
+```bash
+uv tool install surf-cli      # or: pipx install surf-cli, or: pip install surf-cli
+surf --version
+```
+
+With Nix:
+
+```bash
+nix profile install github:saintx/surf-cli          # add ?ref=X.Y.Z to pin a release
+```
+
+## Quick start
+
+The examples run against the reference files shipped with the agent skill:
+
+```bash
+cd plugins/surf/skills/surf/references
+```
+
+A file with no heading named returns the map: frontmatter, then the heading tree, none of the body.
+
+```
+$ surf about.md
+---
+metadata:
+  author:
+    name: Alexander R. Saint Croix
+    github_username: saintx
+    email: alex@saintx.us
+    twitter: alexsaintx
+  surf-version: "0.7.1"
+---
+
+- Surf — About
+  - Overview
+  - When to use
+```
+
+A heading returns that section and stops at the next heading of the same or higher level.
+
+```
+$ surf about.md "When to use"
+## When to use
+
+Invoke when skimming markdown, TeX, or PDF files, checking what a file contains, ...
+```
+
+The same two commands work on TeX, addressed by sectioning commands and the `abstract` environment, and on PDF, addressed by outline bookmarks. `surf.tex` and `surf.pdf` are one paper in two forms and list the same tree from either.
+
+```
+$ surf surf.tex --list
+- abstract
+- Background
+- A Thin Index Shaped by Intent
+- Agentic Context Composition
+- Skills You Can Check
+- Indexes over Indexes
+- Markdown, TeX, and PDF
+- This Paper
+
+$ surf surf.tex "Markdown, TeX, and PDF"
+\section{Markdown, TeX, and PDF}
+
+surf addresses a markdown file by its ATX headings, a TeX file by its sectioning
+commands and its \texttt{abstract} environment, and a PDF by its outline. ...
+
+$ surf surf.pdf "Markdown, TeX, and PDF"
+```
+
+## Addressing
+
+Suppose `guide.md` is:
+
+```markdown
+---
+title: Guide
+tags: [cli, docs]
+---
+# Guide
+
+Intro paragraph.
+
+## Install
+
+### Usage
+
+Install usage text.
+
+## API
+
+### Usage
+
+API usage text.
+
+#### Examples
+
+Deep example.
+```
+
+Its map is:
+
+```
+$ surf guide.md
+---
+title: Guide
+tags: [cli, docs]
+---
+
+- Guide
+  - Install
+    - Usage
+  - API
+    - Usage
+      - Examples
+```
+
+**Get one section.** Name the heading. The section runs to the next heading of the same or higher level, so a parent brings its children.
+
+```
+$ surf guide.md "API"
+## API
+
+### Usage
+
+API usage text.
+
+#### Examples
+
+Deep example.
+```
+
+**Pick between two headings with the same name.** Write the path from the parent. A bare name matches the first occurrence in the file.
+
+```
+$ surf guide.md "API#Usage"
+### Usage
+
+API usage text.
+
+#### Examples
+
+Deep example.
+```
+
+**List only the top N levels.** `--level N` on a listing shows ranks 1 through N.
+
+```
+$ surf guide.md --list --level 2
+- Guide
+  - Install
+  - API
+```
+
+**Extract only at an exact level.** `--level N` on an extract matches rank N and nothing else. `Usage` exists only at rank 3, so rank 2 is not found.
+
+```
+$ surf guide.md "Examples" --level 4
+#### Examples
+
+Deep example.
+
+$ surf guide.md "Usage" --level 2
+Error: heading "Usage" not found in guide.md.
+```
+
+**Use a link as the address.** Obsidian wikilinks and markdown links resolve directly, `#` segments included.
+
+```bash
+surf "[[guide#API#Usage]]"
+surf "[API](guide.md#API)"
+```
+
+**Frontmatter only, or headings only.** `-f` prints the YAML block and nothing else. `--list` prints the tree and no YAML. `--full` prints the YAML and then the named section.
+
+```bash
+surf -f guide.md
+surf --list guide.md
+surf guide.md "Install" --full
+```
+
+**Drop the heading line, or write to a file.**
+
+```bash
+surf guide.md "API" --no-heading
+surf guide.md "API" -o api.md
+```
+
+**What counts as a heading.** On markdown, the ATX heading text. On TeX, the brace title of a sectioning command, plus `abstract` for the abstract environment; `\input` and `\include` of `.tex` files expand relative to the file you name, while graphics, comments, shell pipes, absolute paths, `..` segments, and macro-built paths do not. On PDF, an outline bookmark title; the extract is the page text from that bookmark to the next, and when the next bookmark shares a page, that page is included. Rank 1 is `#` on markdown, the shallowest sectioning command in the TeX file (`\section` in an article), and the outline's top rank on PDF.
+
+Matching ignores case. `surf guide` resolves to `guide.md`; `.tex` and `.pdf` need their suffix. Any other UTF-8 file is addressed as ATX markdown.
+
+**When there is nothing to address.** A file with no headings, or a PDF with no outline, prints `no structural index` and line and byte counts (page and byte counts on PDF), and exits 0. A heading that is not there exits 1 with `Error: heading "X" not found in guide.md.` A missing file or bad usage exits 2.
+
+**Scan a directory.** Frontmatter across many files, no body loaded:
+
+```bash
+ls docs/*.md | xargs -I {} surf -f {}
+```
+
+`surf --help` lists every flag.
+
+## Agent skill
+
+`plugins/surf` packages a skill that teaches an agent how to use surf. It carries a Claude Code manifest, an Agent Plugins 1.0.0 manifest, and the skill itself at `plugins/surf/skills/surf`, in the Agent Skills format that Claude Code, Codex, Gemini CLI, Cursor, and Grok Build read. The skill shells out to `surf`, so install the CLI first.
+
+Claude Code installs it from the marketplace in this repo:
+
+```bash
+claude plugin marketplace add saintx/surf-cli
+claude plugin install surf@surf-cli
+```
+
+Any harness that reads a skills directory takes a copy:
+
+```bash
+cp -R plugins/surf/skills/surf ~/.agents/skills/surf
+```
+
+This checkout links `.agents/skills/surf`, `.claude/skills/surf`, and `.grok/skills/surf` into the plugin, so an agent working in the repo already has it.
+
+The paper in `plugins/surf/skills/surf/references/surf.pdf` (also `surf.tex`) is about what surf can be used to build. surf itself is the primitive.
+
+## Contributing
+
+Development setup, tests, and lint are in [CONTRIBUTING.md](https://github.com/saintx/surf-cli/blob/main/CONTRIBUTING.md). The release procedure is in [RELEASING.md](https://github.com/saintx/surf-cli/blob/main/RELEASING.md).
+
+## License
+
+[MIT](https://github.com/saintx/surf-cli/blob/main/LICENSE).

surf_cli-0.7.1/README.md

@@ -0,0 +1,237 @@
+# surf
+
+List headings, or extract one section by name, from Markdown, TeX, or PDF.
+
+Distribution `surf-cli`. Command `surf`. Python 3.12+; pypdf is the one runtime dependency, for PDF outlines. Only the section you name is printed, so the rest of the file never enters an agent's context.
+
+## Install
+
+```bash
+uv tool install surf-cli      # or: pipx install surf-cli, or: pip install surf-cli
+surf --version
+```
+
+With Nix:
+
+```bash
+nix profile install github:saintx/surf-cli          # add ?ref=X.Y.Z to pin a release
+```
+
+## Quick start
+
+The examples run against the reference files shipped with the agent skill:
+
+```bash
+cd plugins/surf/skills/surf/references
+```
+
+A file with no heading named returns the map: frontmatter, then the heading tree, none of the body.
+
+```
+$ surf about.md
+---
+metadata:
+  author:
+    name: Alexander R. Saint Croix
+    github_username: saintx
+    email: alex@saintx.us
+    twitter: alexsaintx
+  surf-version: "0.7.1"
+---
+
+- Surf — About
+  - Overview
+  - When to use
+```
+
+A heading returns that section and stops at the next heading of the same or higher level.
+
+```
+$ surf about.md "When to use"
+## When to use
+
+Invoke when skimming markdown, TeX, or PDF files, checking what a file contains, ...
+```
+
+The same two commands work on TeX, addressed by sectioning commands and the `abstract` environment, and on PDF, addressed by outline bookmarks. `surf.tex` and `surf.pdf` are one paper in two forms and list the same tree from either.
+
+```
+$ surf surf.tex --list
+- abstract
+- Background
+- A Thin Index Shaped by Intent
+- Agentic Context Composition
+- Skills You Can Check
+- Indexes over Indexes
+- Markdown, TeX, and PDF
+- This Paper
+
+$ surf surf.tex "Markdown, TeX, and PDF"
+\section{Markdown, TeX, and PDF}
+
+surf addresses a markdown file by its ATX headings, a TeX file by its sectioning
+commands and its \texttt{abstract} environment, and a PDF by its outline. ...
+
+$ surf surf.pdf "Markdown, TeX, and PDF"
+```
+
+## Addressing
+
+Suppose `guide.md` is:
+
+```markdown
+---
+title: Guide
+tags: [cli, docs]
+---
+# Guide
+
+Intro paragraph.
+
+## Install
+
+### Usage
+
+Install usage text.
+
+## API
+
+### Usage
+
+API usage text.
+
+#### Examples
+
+Deep example.
+```
+
+Its map is:
+
+```
+$ surf guide.md
+---
+title: Guide
+tags: [cli, docs]
+---
+
+- Guide
+  - Install
+    - Usage
+  - API
+    - Usage
+      - Examples
+```
+
+**Get one section.** Name the heading. The section runs to the next heading of the same or higher level, so a parent brings its children.
+
+```
+$ surf guide.md "API"
+## API
+
+### Usage
+
+API usage text.
+
+#### Examples
+
+Deep example.
+```
+
+**Pick between two headings with the same name.** Write the path from the parent. A bare name matches the first occurrence in the file.
+
+```
+$ surf guide.md "API#Usage"
+### Usage
+
+API usage text.
+
+#### Examples
+
+Deep example.
+```
+
+**List only the top N levels.** `--level N` on a listing shows ranks 1 through N.
+
+```
+$ surf guide.md --list --level 2
+- Guide
+  - Install
+  - API
+```
+
+**Extract only at an exact level.** `--level N` on an extract matches rank N and nothing else. `Usage` exists only at rank 3, so rank 2 is not found.
+
+```
+$ surf guide.md "Examples" --level 4
+#### Examples
+
+Deep example.
+
+$ surf guide.md "Usage" --level 2
+Error: heading "Usage" not found in guide.md.
+```
+
+**Use a link as the address.** Obsidian wikilinks and markdown links resolve directly, `#` segments included.
+
+```bash
+surf "[[guide#API#Usage]]"
+surf "[API](guide.md#API)"
+```
+
+**Frontmatter only, or headings only.** `-f` prints the YAML block and nothing else. `--list` prints the tree and no YAML. `--full` prints the YAML and then the named section.
+
+```bash
+surf -f guide.md
+surf --list guide.md
+surf guide.md "Install" --full
+```
+
+**Drop the heading line, or write to a file.**
+
+```bash
+surf guide.md "API" --no-heading
+surf guide.md "API" -o api.md
+```
+
+**What counts as a heading.** On markdown, the ATX heading text. On TeX, the brace title of a sectioning command, plus `abstract` for the abstract environment; `\input` and `\include` of `.tex` files expand relative to the file you name, while graphics, comments, shell pipes, absolute paths, `..` segments, and macro-built paths do not. On PDF, an outline bookmark title; the extract is the page text from that bookmark to the next, and when the next bookmark shares a page, that page is included. Rank 1 is `#` on markdown, the shallowest sectioning command in the TeX file (`\section` in an article), and the outline's top rank on PDF.
+
+Matching ignores case. `surf guide` resolves to `guide.md`; `.tex` and `.pdf` need their suffix. Any other UTF-8 file is addressed as ATX markdown.
+
+**When there is nothing to address.** A file with no headings, or a PDF with no outline, prints `no structural index` and line and byte counts (page and byte counts on PDF), and exits 0. A heading that is not there exits 1 with `Error: heading "X" not found in guide.md.` A missing file or bad usage exits 2.
+
+**Scan a directory.** Frontmatter across many files, no body loaded:
+
+```bash
+ls docs/*.md | xargs -I {} surf -f {}
+```
+
+`surf --help` lists every flag.
+
+## Agent skill
+
+`plugins/surf` packages a skill that teaches an agent how to use surf. It carries a Claude Code manifest, an Agent Plugins 1.0.0 manifest, and the skill itself at `plugins/surf/skills/surf`, in the Agent Skills format that Claude Code, Codex, Gemini CLI, Cursor, and Grok Build read. The skill shells out to `surf`, so install the CLI first.
+
+Claude Code installs it from the marketplace in this repo:
+
+```bash
+claude plugin marketplace add saintx/surf-cli
+claude plugin install surf@surf-cli
+```
+
+Any harness that reads a skills directory takes a copy:
+
+```bash
+cp -R plugins/surf/skills/surf ~/.agents/skills/surf
+```
+
+This checkout links `.agents/skills/surf`, `.claude/skills/surf`, and `.grok/skills/surf` into the plugin, so an agent working in the repo already has it.
+
+The paper in `plugins/surf/skills/surf/references/surf.pdf` (also `surf.tex`) is about what surf can be used to build. surf itself is the primitive.
+
+## Contributing
+
+Development setup, tests, and lint are in [CONTRIBUTING.md](https://github.com/saintx/surf-cli/blob/main/CONTRIBUTING.md). The release procedure is in [RELEASING.md](https://github.com/saintx/surf-cli/blob/main/RELEASING.md).
+
+## License
+
+[MIT](https://github.com/saintx/surf-cli/blob/main/LICENSE).

{surf_cli-0.7.0 → surf_cli-0.7.1}/flake.nix

@@ -55,7 +55,7 @@
 
         surf = pythonPkgs.buildPythonApplication {
           pname = "surf";
-          version = "0.7.0";
+          version = "0.7.1";
           src = cliSrc;
           pyproject = true;
 

{surf_cli-0.7.0 → surf_cli-0.7.1}/plugins/surf/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "surf",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Extract a markdown heading, TeX section, or PDF outline item without loading the rest of the file. Skill for agents using the surf CLI.",
   "author": { "name": "Alexander R. Saint Croix", "email": "alex@saintx.us" },
   "homepage": "https://github.com/saintx/surf-cli",

{surf_cli-0.7.0 → surf_cli-0.7.1}/plugins/surf/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "surf",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Extract a markdown heading, TeX section, or PDF outline item without loading the rest of the file. Skill for agents using the surf CLI.",
   "author": { "name": "Alexander R. Saint Croix", "email": "alex@saintx.us", "url": "https://github.com/saintx" },
   "homepage": "https://github.com/saintx/surf-cli",

{surf_cli-0.7.0 → surf_cli-0.7.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "surf-cli"
-version = "0.7.0"
-description = "Extract markdown, TeX, or PDF outline sections by heading with Obsidian link support"
+version = "0.7.1"
+description = "List headings, or extract one section by name, from Markdown, TeX, or PDF."
 readme = "README.md"
 license = { file = "LICENSE" }
 authors = [{ name = "Alexander R. Saint Croix", email = "alex@saintx.us" }]

{surf_cli-0.7.0 → surf_cli-0.7.1}/src/surf/__init__.py

@@ -1,5 +1,5 @@
 # __init__.py
 """surf-cli: heading-addressed markdown, TeX, and PDF extract."""
 
-__version__ = "0.7.0"
+__version__ = "0.7.1"
 __version_tag__ = f"surf-v{__version__}"

{surf_cli-0.7.0 → surf_cli-0.7.1}/src/surf/logic.py

@@ -41,6 +41,8 @@ from surf.models import (
 )
 
 _HEADING_RE = re.compile(r"^(#{1,6})\s+(.+)$")
+_FENCE_OPEN_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$")
+_FENCE_CLOSE_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})\s*$")
 _TEX_LEVEL: Mapping[TexCommand, HeadingLevel] = {
     TexCommand.PART: HeadingLevel(1),
     TexCommand.CHAPTER: HeadingLevel(2),
@@ -108,9 +110,42 @@ def parse_link(target: CliTarget) -> ParsedLink:
     return ParsedLink(file_ref=FileRef(stripped) if stripped else None, heading_path=None)
 
 
+def _fence_open(line: str) -> str | None:
+    """Return the fence string when line opens a fenced code block, else None.
+
+    CommonMark: up to three spaces of indent, then three or more backticks or
+    tildes. A backtick fence's info string may not contain a backtick.
+    """
+    m = _FENCE_OPEN_RE.match(line)
+    if m is None:
+        return None
+    fence, info = m.group(1), m.group(2)
+    if fence[0] == "`" and "`" in info:
+        return None
+    return fence
+
+
+def _fence_closes(line: str, open_fence: str) -> bool:
+    """A closing fence uses the same character and is at least as long."""
+    m = _FENCE_CLOSE_RE.match(line)
+    if m is None:
+        return False
+    fence = m.group(1)
+    return fence[0] == open_fence[0] and len(fence) >= len(open_fence)
+
+
 def parse_headings(lines: Sequence[str]) -> tuple[HeadingRecord, ...]:
+    """ATX headings outside fenced code blocks. A `#` line inside a fence is code."""
     records: list[HeadingRecord] = []
+    open_fence: str | None = None
     for i, line in enumerate(lines):
+        if open_fence is not None:
+            if _fence_closes(line, open_fence):
+                open_fence = None
+            continue
+        open_fence = _fence_open(line)
+        if open_fence is not None:
+            continue
         m = _HEADING_RE.match(line)
         if m:
             records.append(

{surf_cli-0.7.0 → surf_cli-0.7.1}/src/surf/test_logic.py

@@ -537,3 +537,60 @@ def test_format_empty_pdf_index_reports_pages_and_bytes() -> None:
         "pages: 18",
         "bytes: 13153200",
     ]
+
+
+FENCED_MD = """# Doc
+
+## Real
+
+```markdown
+# Not a heading
+## Also not
+```
+
+~~~
+### Tilde fenced
+~~~
+
+````md
+```
+# Nested shorter fence stays open
+```
+````
+
+## After
+
+    # Indented code, not a heading
+
+```
+# Unclosed fence runs to the end
+## Still code
+"""
+
+
+def test_parse_headings_skips_fenced_code_blocks() -> None:
+    headings = parse_headings(FENCED_MD.splitlines())
+    assert [str(record.text) for record in headings] == ["Doc", "Real", "After"]
+
+
+def test_extract_section_keeps_fenced_hash_lines_in_body() -> None:
+    lines = FENCED_MD.splitlines()
+    result = extract_section(lines, hp("Real"))
+    assert result is not None
+    body = "\n".join(result.lines)
+    assert "# Not a heading" in body
+    assert "### Tilde fenced" in body
+    assert "# Nested shorter fence stays open" in body
+    assert "## After" not in body
+
+
+def test_backtick_fence_info_string_with_backtick_is_not_a_fence() -> None:
+    lines = ["# Top", "``` not `a` fence", "## Heading", "```"]
+    headings = parse_headings(lines)
+    assert [str(record.text) for record in headings] == ["Top", "Heading"]
+
+
+def test_closing_fence_must_match_char_and_length() -> None:
+    lines = ["# Top", "````", "~~~~", "```", "## Inside", "````", "## Outside"]
+    headings = parse_headings(lines)
+    assert [str(record.text) for record in headings] == ["Top", "Outside"]

{surf_cli-0.7.0 → surf_cli-0.7.1}/uv.lock

@@ -380,7 +380,7 @@ wheels = [
 
 [[package]]
 name = "surf-cli"
-version = "0.7.0"
+version = "0.7.1"
 source = { editable = "." }
 dependencies = [
     { name = "pypdf" },

surf_cli-0.7.0/PKG-INFO

@@ -1,177 +0,0 @@
-Metadata-Version: 2.5
-Name: surf-cli
-Version: 0.7.0
-Summary: Extract markdown, TeX, or PDF outline sections by heading with Obsidian link support
-Project-URL: Homepage, https://github.com/saintx/surf-cli
-Project-URL: Repository, https://github.com/saintx/surf-cli
-Project-URL: Issues, https://github.com/saintx/surf-cli/issues
-Project-URL: Author, https://github.com/saintx
-Author-email: "Alexander R. Saint Croix" <alex@saintx.us>
-License: MIT License
-        
-        Copyright (c) 2026 Alexander R. Saint Croix
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: pypdf>=6.17.0
-Description-Content-Type: text/markdown
-
-# surf
-
-Extract one section of a markdown, TeX, or PDF file by its heading. The rest of the file never loads.
-
-```bash
-uv tool install surf-cli
-cd plugins/surf/skills/surf/references
-```
-
-A file with no heading named returns the map, frontmatter and then headings, and none of the body:
-
-```
-$ surf about.md
----
-metadata:
-  author:
-    name: Alexander R. Saint Croix
-    github_username: saintx
-    email: alex@saintx.us
-    twitter: alexsaintx
-  surf-version: "0.7.0"
----
-
-- Surf — About
-  - Overview
-  - When to use
-```
-
-A heading returns that section and stops at the next heading of the same or higher level:
-
-```
-$ surf about.md "When to use"
-## When to use
-
-Invoke when skimming markdown, TeX, or PDF files, checking what a file contains,
-listing structure, extracting a named address, or batch-scanning metadata across
-a directory. See `surf --help` for CLI flags. Skip when the full body is already
-needed. ...
-```
-
-The same two commands work on TeX, addressed by sectioning commands and the `abstract` environment, and on PDF, addressed by outline bookmarks. The whitepaper in this directory ships in both forms and lists the same tree from either:
-
-```
-$ surf surf.tex --list
-- abstract
-- Background
-- A Thin Index Shaped by Intent
-- Agentic Context Composition
-- Skills You Can Check
-- Indexes over Indexes
-- Markdown, TeX, and PDF
-- This Paper
-
-$ surf surf.pdf "Skills You Can Check"
-```
-
-surf exists so that agent skills can be thin. The `SKILL.md` beside these files is a table of intents, each resolving to `surf path "Heading"`, over reference material the agent never reads whole. `surf.pdf` explains why the tool was built and what that pattern makes possible.
-
-## Addressing
-
-`surf --list file.md` is the heading tree without YAML. `surf -f file.md` is YAML only. Nested paths (`Overview#Usage`) select a child when the same name appears under different parents.
-
-A heading is an address: ATX display text on markdown, brace title on TeX, the TeX `abstract` environment (addressed as `abstract`), or an outline bookmark title on PDF. On markdown and TeX the return value is that section through the next heading of the same or higher level. On PDF it is dest-to-next-dest page text; when the next dest is on the same page, that dest page is included.
-
-`--level` is 1 at the top of the heading tree. On markdown that is `#`. On TeX it is the shallowest command in the file, so `--level 1` is `\section` in an article. On PDF it is the outline's native rank. Listing with `--level N` includes ranks 1 through N. Named extract uses N as an exact match.
-
-TeX `\input` and `\include` of `.tex` files are expanded relative to the file you name. Graphics, comments, shell pipes, and macro-constructed paths are not.
-
-If the file has no headings, or a PDF has no outline, surf prints that it has no structural index, with line and byte counts on markdown and TeX, or page and byte counts on PDF. It does not dump the body.
-
-Python 3.12+. pypdf is the runtime dependency for PDF outline addressing.
-
-## Agent skill
-
-`plugins/surf` packages the skill for agents. It carries a Claude Code manifest, an Agent Plugins 1.0.0 manifest, and the skill itself at `plugins/surf/skills/surf`, in the Agent Skills format that Claude Code, Codex, Gemini CLI, Cursor, and Grok Build read.
-
-Claude Code installs it from the marketplace in this repo:
-
-```bash
-claude plugin marketplace add saintx/surf-cli
-claude plugin install surf@surf-cli
-```
-
-Any harness that reads a skills directory takes a copy of the skill:
-
-```bash
-cp -R plugins/surf/skills/surf ~/.agents/skills/surf
-```
-
-The repo also carries `.agents/skills/surf`, `.claude/skills/surf`, and `.grok/skills/surf` as symlinks into the plugin, so an agent working in this checkout has the skill available.
-
-## Install
-
-The distribution name is `surf-cli`. The command is `surf`. Python 3.12+.
-
-```bash
-uv tool install surf-cli
-surf --version
-```
-
-```bash
-pipx install surf-cli
-surf --version
-```
-
-```bash
-pip install surf-cli
-```
-
-### Nix
-
-From a local clone, install the flake into the nix profile:
-
-```bash
-nix profile install "git+file://${PWD}"
-surf --version
-```
-
-Pin a tagged release with `?ref=X.Y.Z`. If `surf` is already in the profile under a different flake URL, remove it first:
-
-```bash
-nix profile remove surf
-nix profile install "git+file://${PWD}?ref=X.Y.Z"
-```
-
-`scripts/deploy.sh` syncs, tests, and retargets the profile at the latest local semver tag.
-
-## Releasing
-
-Version locations, the bump checklist, tagging, and nix profile deployment are in [RELEASING.md](RELEASING.md).
-
-## Development
-
-```bash
-nix develop
-```
-
-## Tests
-
-```bash
-scripts/test.sh    # uv run pytest src/surf
-```

surf_cli-0.7.0/README.md

@@ -1,142 +0,0 @@
-# surf
-
-Extract one section of a markdown, TeX, or PDF file by its heading. The rest of the file never loads.
-
-```bash
-uv tool install surf-cli
-cd plugins/surf/skills/surf/references
-```
-
-A file with no heading named returns the map, frontmatter and then headings, and none of the body:
-
-```
-$ surf about.md
----
-metadata:
-  author:
-    name: Alexander R. Saint Croix
-    github_username: saintx
-    email: alex@saintx.us
-    twitter: alexsaintx
-  surf-version: "0.7.0"
----
-
-- Surf — About
-  - Overview
-  - When to use
-```
-
-A heading returns that section and stops at the next heading of the same or higher level:
-
-```
-$ surf about.md "When to use"
-## When to use
-
-Invoke when skimming markdown, TeX, or PDF files, checking what a file contains,
-listing structure, extracting a named address, or batch-scanning metadata across
-a directory. See `surf --help` for CLI flags. Skip when the full body is already
-needed. ...
-```
-
-The same two commands work on TeX, addressed by sectioning commands and the `abstract` environment, and on PDF, addressed by outline bookmarks. The whitepaper in this directory ships in both forms and lists the same tree from either:
-
-```
-$ surf surf.tex --list
-- abstract
-- Background
-- A Thin Index Shaped by Intent
-- Agentic Context Composition
-- Skills You Can Check
-- Indexes over Indexes
-- Markdown, TeX, and PDF
-- This Paper
-
-$ surf surf.pdf "Skills You Can Check"
-```
-
-surf exists so that agent skills can be thin. The `SKILL.md` beside these files is a table of intents, each resolving to `surf path "Heading"`, over reference material the agent never reads whole. `surf.pdf` explains why the tool was built and what that pattern makes possible.
-
-## Addressing
-
-`surf --list file.md` is the heading tree without YAML. `surf -f file.md` is YAML only. Nested paths (`Overview#Usage`) select a child when the same name appears under different parents.
-
-A heading is an address: ATX display text on markdown, brace title on TeX, the TeX `abstract` environment (addressed as `abstract`), or an outline bookmark title on PDF. On markdown and TeX the return value is that section through the next heading of the same or higher level. On PDF it is dest-to-next-dest page text; when the next dest is on the same page, that dest page is included.
-
-`--level` is 1 at the top of the heading tree. On markdown that is `#`. On TeX it is the shallowest command in the file, so `--level 1` is `\section` in an article. On PDF it is the outline's native rank. Listing with `--level N` includes ranks 1 through N. Named extract uses N as an exact match.
-
-TeX `\input` and `\include` of `.tex` files are expanded relative to the file you name. Graphics, comments, shell pipes, and macro-constructed paths are not.
-
-If the file has no headings, or a PDF has no outline, surf prints that it has no structural index, with line and byte counts on markdown and TeX, or page and byte counts on PDF. It does not dump the body.
-
-Python 3.12+. pypdf is the runtime dependency for PDF outline addressing.
-
-## Agent skill
-
-`plugins/surf` packages the skill for agents. It carries a Claude Code manifest, an Agent Plugins 1.0.0 manifest, and the skill itself at `plugins/surf/skills/surf`, in the Agent Skills format that Claude Code, Codex, Gemini CLI, Cursor, and Grok Build read.
-
-Claude Code installs it from the marketplace in this repo:
-
-```bash
-claude plugin marketplace add saintx/surf-cli
-claude plugin install surf@surf-cli
-```
-
-Any harness that reads a skills directory takes a copy of the skill:
-
-```bash
-cp -R plugins/surf/skills/surf ~/.agents/skills/surf
-```
-
-The repo also carries `.agents/skills/surf`, `.claude/skills/surf`, and `.grok/skills/surf` as symlinks into the plugin, so an agent working in this checkout has the skill available.
-
-## Install
-
-The distribution name is `surf-cli`. The command is `surf`. Python 3.12+.
-
-```bash
-uv tool install surf-cli
-surf --version
-```
-
-```bash
-pipx install surf-cli
-surf --version
-```
-
-```bash
-pip install surf-cli
-```
-
-### Nix
-
-From a local clone, install the flake into the nix profile:
-
-```bash
-nix profile install "git+file://${PWD}"
-surf --version
-```
-
-Pin a tagged release with `?ref=X.Y.Z`. If `surf` is already in the profile under a different flake URL, remove it first:
-
-```bash
-nix profile remove surf
-nix profile install "git+file://${PWD}?ref=X.Y.Z"
-```
-
-`scripts/deploy.sh` syncs, tests, and retargets the profile at the latest local semver tag.
-
-## Releasing
-
-Version locations, the bump checklist, tagging, and nix profile deployment are in [RELEASING.md](RELEASING.md).
-
-## Development
-
-```bash
-nix develop
-```
-
-## Tests
-
-```bash
-scripts/test.sh    # uv run pytest src/surf
-```