structured-gist 0.9.0__tar.gz

structured_gist-0.9.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.DS_Store

structured_gist-0.9.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+Release notes for tagged versions. The release workflow publishes the section that matches the tag. The full per-version history, including releases before 0.9.0, is in [skills/structured-gist/CHANGELOG.md](skills/structured-gist/CHANGELOG.md).
+
+## [Unreleased]
+
+## [0.9.0] — 2026-10-19
+
+First release on PyPI. It covers the unreleased 0.7.0 and 0.8.0 work and the changes below.
+
+### Added
+
+- Python package `structured-gist` on PyPI. It installs the stdlib-only outline linter as the `structured-gist-lint` command and the `structured_gist` import package.
+- Linter rule R17, advisory only: `structured-gist-lint --advisory` flags a `↪` explanation leaf that holds 2 or more commas outside code, quotes and parentheses. Advisories never change the exit code. R17 stays advisory until hedge detection exists ([#9](https://github.com/domattioli/structured-gist/issues/9)).
+- `SKILL.md` pre-emit check: a six-step pass over word caps, enumerator case, delimiter tails, arrow rarity, sibling families and line width, run before an outline is sent ([#22](https://github.com/domattioli/structured-gist/issues/22)).
+- Smoke-test ratchet on the benchmark renderings: `tests/renderings_lint_baseline.json` holds per-rule violation counts, and smoke fails when any rule's count rises ([#22](https://github.com/domattioli/structured-gist/issues/22)).
+- Tag-push release workflow: tests, version gate, PyPI publish and GitHub release. Zenodo archives each GitHub release under the concept DOI.
+
+### Changed
+
+- Benchmark metric is `fact_retention_delta`, replacing `word_count_reduction_pct` (0.7.0). Output length is no longer the headline number ([#28](https://github.com/domattioli/structured-gist/issues/28)).
+- The `block` line budget follows the terminal: `width auto` resolves to the terminal width minus 8, clamped to 32-120, and 64 when no width is known (0.8.0).
+- Citation metadata names Dominik O. Mattioli with ORCID 0000-0002-7327-6337.

structured_gist-0.9.0/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the
+      purposes of this License, Derivative Works shall not include works
+      that remain separable from, or merely link (or bind by name) to the
+      interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on
+      behalf of the copyright owner. For the purposes of this definition,
+      "submitted" means any form of electronic, verbal, or written
+      communication sent to the Licensor or its representatives, including
+      but not limited to communication on electronic mailing lists, source
+      code control systems, and issue tracking systems that are managed by,
+      or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2024-2026 the authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

structured_gist-0.9.0/NOTICE

@@ -0,0 +1,11 @@
+structured-gist
+Copyright 2026 Dominik Mattioli and structured-gist contributors
+
+This product is licensed under the Apache License, Version 2.0
+(see LICENSE). Redistributions of this work, or of derivative works,
+must retain this NOTICE file.
+
+Please cite this work when you use it:
+  Mattioli, D. structured-gist. Zenodo. https://doi.org/10.5281/zenodo.22670068
+Source: https://github.com/domattioli/structured-gist
+Machine-readable citation: CITATION.cff

structured_gist-0.9.0/PKG-INFO

@@ -0,0 +1,361 @@
+Metadata-Version: 2.5
+Name: structured-gist
+Version: 0.9.0
+Summary: Deterministic linter for structured-gist nested lecture-note outlines
+Project-URL: Homepage, https://github.com/domattioli/structured-gist
+Project-URL: Repository, https://github.com/domattioli/structured-gist
+Project-URL: Issues, https://github.com/domattioli/structured-gist/issues
+Project-URL: DOI, https://doi.org/10.5281/zenodo.22670068
+Author: Dominik O. Mattioli
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agent-skill,claude-code,linter,outline,structured-notes
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# structured-gist
+
+<p align="center"><img src="https://raw.githubusercontent.com/domattioli/structured-gist/main/docs/assets/hero.svg" alt="structured-gist: Input, agentic-AI word vomit; Output, a skimmable outline" width="100%"></p>
+
+[![Release](https://img.shields.io/github/v/release/domattioli/structured-gist)](https://github.com/domattioli/structured-gist/releases)
+![License](https://img.shields.io/badge/license-Apache--2.0-blue)
+[![Tests](https://github.com/domattioli/structured-gist/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/domattioli/structured-gist/actions/workflows/tests.yml)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22670068.svg)](https://doi.org/10.5281/zenodo.22670068)
+[![Mentioned in Awesome Claude Skills](https://awesome.re/mentioned-badge.svg)](https://github.com/karanb192/awesome-claude-skills)
+
+A skill turning agentic-AI word vomit into a skimmable gist. Information is encoded intuitively within a nested bulleted structure and via node depth; prose stays confined to explanation nodes. 
+
+## Contents
+
+1. [Motivation](#1-motivation)
+2. [Installation](#2-installation)
+3. [Usage](#3-usage)
+4. [Method](#4-method)
+5. [Benchmarks](#5-benchmarks)
+6. [Limitations](#6-limitations)
+7. [Future work](#7-future-work)
+8. [Documentation](#8-documentation)
+9. [Contributing](#9-contributing)
+10. [Reuse and training](#10-reuse-and-training)
+11. [License](#11-license)
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 1. Motivation
+
+Claude's explanatory prose is increasingly a dense, rambling, incomprehensible mess with unexplained jargon and padded with filler. Word-count compression does not fix this. For instance, [caveman](https://github.com/JuliusBrussee/caveman), can shorten Claudish prose but does not reorganize it. Other mechanisms like [claudish-to-english](https://github.com/gvzdv/claudish-to-english) still rely on unstructured prose. Both are useful, but neither deterministically cuts through the noise.
+
+What's missing is structure: concept, sub-concept, and the relationship between them. This is also how a well-built lecture teaches a complex subject, and how a good slide deck gets built: one concept per slide, minimal words, relationships carried by layout instead of prose.
+ 
+`structured-gist` renders that decomposition as an explicit tree instead of a paragraph the reader has to parse for it. We can't get rid of the AI slop, but we can push it to the peripheries and help you get to the gist faster.
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 2. Installation
+
+```bash
+/plugin marketplace add domattioli/structured-gist
+/plugin install structured-gist
+```
+
+The outline linter and claim-list renderer also ship on PyPI, stdlib only:
+
+```bash
+pip install structured-gist
+structured-gist-lint your_output.md              # exit 1 on any violation
+structured-gist-lint --advisory your_output.md   # also print R17 advisories
+structured-gist-claims your_output.md            # JSONL claim list
+```
+
+In Python, `from structured_gist.lint_outline import lint_text`.
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 3. Usage
+
+```bash
+/structured-gist [block [width N|auto]|responsive]
+```
+
+Output uses one granularity level, `standard`. The `skim` and `deep` levels are archived (see [Future work](#7-future-work)). No mode given defaults to `block` on all surfaces; pick `responsive` explicitly for a real GFM nested list on a markdown-rendering surface. The `block` line budget is 64 columns by default. `width auto` sizes it to the terminal (terminal width minus 8, clamped to 32-120), and `width N` sets it exactly with no cap.
+
+Two opt-in presets are also available: the summary preset (`/structured-gist summary`, alias `session-summary`) and the report preset (`/structured-gist report`, alias `findings`).
+
+Trigger phrases: "structured-gist", "sg", "gist mode", "gist this", "outline this", "bullet this", "notes mode", "structure this", "break this down", "distill this", "give me the gist", "make this skimmable", "tighten this up", "condense this".
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 4. Method
+
+The example below compares Claude Opus's unadulterated description of how this skill works vs. the dogfood-ed skill output. It covers the marker taxonomy and overall gist of how `structured-gist` works.
+
+As a paragraph, it reads:
+
+> structured-gist is a documentation tool that replaces verbose prose summaries with compact outlines, trading paragraphs a reader has to work through for a structure they can take in at a glance. Rather than relying on sentence grammar to carry relationships, it uses a role hierarchy in which each node's position in the tree encodes its meaning: a concept sits at the root, named attributes hang beneath it, ordinal or nominal enumerators sequence the branches, and prose explanations appear only as leaves. Because a format like that decays quickly when written by hand, a linter enforces it with fifteen rules in total. Two representative examples: one flags shallow-depth stalling, where a node occupies a level without contributing any real structure beneath it, and another detects punctuation-spliced facts, where two distinct claims are welded together with a comma or semicolon instead of being split into separate sibling nodes. The linter lives at lint_outline.py, depends only on the standard library, and applies all fifteen rules automatically. It fits session recaps, cause-chain explanations, and GitHub issue and PR comments: anywhere a reader needs to skim a structure rather than parse a paragraph for it.
+
+Rendered as an outline at `standard` granularity in `block` mode, the same content drops 68% from 190 to 61 words (list markers not counted). The drop comes from removing connective prose, not from rewording sentences. The tree also cuts parsing cost for the reader, but [Future work](#7-future-work) needs to quantify this.
+
+```text
+- structured-gist
+    ▸ Purpose
+        ↪ replaces verbose prose summaries with compact
+        outlines a reader takes in at a glance
+    ▸ Mechanism
+        ↪ role hierarchy, not sentence grammar, carries
+        relationships: node position encodes meaning
+    ▸ Role ladder
+        i. concept
+        ii. attribute
+        iii. enumerator
+        iv. explanation
+- Linter
+    ▸ Rationale
+        ↪ the format decays quickly when hand-written
+    ▸ Rules
+        a. shallow-depth stalling
+        b. punctuation-spliced facts
+    ▸ Implementation
+        a. lint_outline.py
+        b. stdlib-only
+- Fit
+    A. session recaps
+    B. cause-chain explanations
+    C. GitHub issue + PR comments
+```
+
+There are two active render modes. `block` is the default on all surfaces; `responsive` is opt-in for GitHub issue/PR/comment bodies and chat-app replies. Both are documented, with worked examples, in `skills/structured-gist/SKILL.md` under `## Render modes` and `reference/render-modes.md`.
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 5. Benchmarks
+
+**Key takeaways**
+
+- Standard depth keeps most of the meaning. Retention is 0.37 at skim, 0.89 at standard, 0.99 at deep. Since v0.6.0, `standard` is the only shipped level.
+- Shorter is not better. Compression correlates negatively with usefulness (r = -0.75), so it is reported as a cost.
+- Losses come from omission and dropped relations. In round 1, no judged fact was ever reworded into a wrong meaning.
+- On 42 external cases (QMSum, Qasper, HotpotQA), relations are lost more often than facts.
+
+Representative measurements from the skill's version history, one metric per column so values in the same column can be compared across versions. Most versions only exercise one metric, so most cells are blank by design (`—`); a filled cell means that version measured that metric. See the [full benchmark ledger](skills/structured-gist/tests/benchmark.md) for methodology and complete history.
+
+| Version | Word count | Outline-quality composite | Rules gated | Tests passing | Weighted retention (skim → standard → deep) | Notes |
+|---|---|---|---|---|---|---|
+| v0.2.9 | **147 → 88 (-40.1%)** | — | — | — | — | Dense paragraph vs. skim outline, same content. |
+| v0.3.7 | **19 → 24 (+26.3%)** | — | — | — | — | Block mode vs. responsive mode, same tree; GFM bullet-token artifact, not a regression. |
+| v0.4.0 | — | **0.549 → 0.760** | — | — | — | Direct prompt vs. experimental KG mode, 20-source corpus; KG mode wins structure but loses retention. Not shipped: see [Future work](#7-future-work). |
+| v0.4.2 | — | — | **11 → 15** | **33 → 46** | — | Linter rule coverage. |
+| v0.4.3 | — | — | — | **46 → 63** | — | Rename and trigger-phrase expansion; no rule-logic change. |
+| Eval only (#10) | — | — | — | — | **0.37 → 0.89 → 0.99** | Semantic-compression suite: 8 curated regression/pressure-test cases scored against gold fact lists; Sonnet ran on 8/8, Haiku on 3/8, full-suite Claude Opus run planned. Compression correlated *negatively* with usefulness (**r = -0.75**), so it is reported as a separate cost, never blended into the quality score. |
+
+Word count, rule/test coverage, and semantic retention (`skills/structured-gist/benchmarks/semantic-compression/`) are the metrics tracked today. Other metrics (reader comprehension, parse time) remain open; see [Future work](#7-future-work) for status and how to propose one.
+
+Third-party dataset licenses and attribution: see [skills/structured-gist/benchmarks/semantic-compression/external-validation/THIRD_PARTY_NOTICES.md](skills/structured-gist/benchmarks/semantic-compression/external-validation/THIRD_PARTY_NOTICES.md).
+
+<details>
+<summary>Worked example: registrar-hedge (before / after, recorded Opus rendering at standard granularity)</summary>
+
+<!-- README-EXAMPLE:START -->
+### registrar-hedge (Before / After)
+
+#### Before (source)
+
+```
+Task: migrate the domain acme-studio.com from the old Squarespace site to an
+already-deployed Cloudflare Pages site. Guide me click-by-click; I'll be
+logged into the relevant dashboards and can screen-share tabs.
+
+Context:
+- New site: Cloudflare Pages project "acme-studio", live at
+  https://acme-studio.pages.dev (direct wrangler uploads, not git-connected).
+  Cloudflare account name: personal-account.
+- CRITICAL: the same Cloudflare account also hosts my personal site (project
+  "personal-portfolio" / personal-portfolio.pages.dev). Do not touch that project or its DNS.
+- Old site: Squarespace, still live at acme-studio.com. It must remain
+  intact as a rollback target for ~2 weeks after cutover. Prefer a DNS-record
+  cutover I can revert in minutes; avoid destructive steps (do not cancel the
+  Squarespace subscription, do not delete the Squarespace site, do not
+  transfer the domain registration itself right now).
+- Registrar is unconfirmed - likely Squarespace Domains (site was built
+  there), possibly Google Domains legacy or another registrar. Step 1 is
+  identifying it with me (whois + what the Squarespace/Domains dashboard shows).
+
+What I need from you, in order:
+1. Identify registrar + current DNS host for acme-studio.com; list current
+   DNS records so we have a written rollback snapshot before changing anything.
+2. Decide the cleanest path for pointing apex + www at the Pages project.
+   Constraint check: if the DNS stays at Squarespace, confirm whether its DNS
+   supports what the apex needs (CNAME flattening/ALIAS); if not, walk me
+   through moving just DNS hosting to Cloudflare (add site as a free zone,
+   import records, switch nameservers) while keeping registration where it is,
+   and note that this weakens the "instant rollback" property - tell me the
+   actual rollback procedure and time for whichever path we take.
+3. Lower TTLs first if the current host allows it.
+4. In Cloudflare Pages > acme-studio > Custom domains: add acme-studio.com
+   and www.acme-studio.com, then make the DNS changes it prescribes.
+5. Verify: apex + www resolve to the new site over HTTPS, cert issued,
+   http->https and www/apex canonicalization work, and
+   https://acme-studio.com/about (extensionless) returns 200.
+6. Give me the exact rollback steps as a saved note, and remind me to submit
+   the sitemap in Google Search Console after cutover.
+
+Known open issue, for your awareness: the site's contact form backend is not
+functional yet (being fixed separately). If we complete DNS today, that's
+accepted - launch decision is mine.
+
+```
+
+#### After (structured-gist rendering)
+
+```text
+- Domain migration
+    ▸ Goal
+        ↪ move acme-studio.com from the old Squarespace site
+        to an already-deployed Cloudflare Pages site
+    ▸ Mode
+        ↪ guide click-by-click; the user is logged into the
+        relevant dashboards and can screen-share tabs
+- New site
+    ▸ Project
+        a. Cloudflare Pages project "acme-studio"
+        b. live at https://acme-studio.pages.dev
+    ▸ Deploy method
+        ↪ direct wrangler uploads, not git-connected
+    ▸ Account
+        ↪ the Cloudflare account name is personal-account
+- Protected project
+    ▸ Severity
+        ↪ the user marks this one CRITICAL
+    ▸ Identity
+        a. project "personal-portfolio"
+        b. personal-portfolio.pages.dev
+    ▸ Rule
+        ↪ the same account hosts it, so do not touch that
+        project or its DNS
+- Old site
+    ▸ State
+        ↪ Squarespace, still live at acme-studio.com
+    ▸ Retention
+        ↪ it must remain intact as a rollback target for
+        about two weeks after cutover
+    ▸ Preference
+        ↪ prefer a DNS-record cutover revertible in minutes
+    ▸ Avoid
+        a. cancelling the Squarespace subscription
+        b. deleting the Squarespace site
+        c. transferring the registration right now
+- Registrar unconfirmed
+    ▸ Candidates
+        a. Squarespace Domains, likely
+        b. Google Domains legacy, possibly
+        c. another registrar
+    ▸ First step
+        ↪ identify it with the user, from whois and what
+        the Squarespace/Domains dashboard shows
+- Requested steps
+    I. identify registrar + current DNS host
+    II. decide the apex and www path
+    III. lower TTLs first
+    IV. add the custom domains in Pages
+    V. verify the new site end to end
+    VI. rollback note + sitemap reminder
+- Known open issue
+    ▸ Contact form
+        ↪ the site's contact form backend is not functional
+        yet and is being fixed separately
+    ▸ Accepted
+        ↪ completing DNS today is accepted; the launch
+        decision is the user's
+
+```
+
+**Metrics:**
+- Source: 381 words
+- Rendering: 272 words
+- Compression: 28.6%
+
+**Key structure:**
+- The registrar hedge is the concept node `Registrar unconfirmed`, so the uncertainty is stated on the node itself
+- Its `▸ Candidates` attribute lists three enumerated children (a./b./c.), each keeping its own qualifier: Squarespace Domains as likely, Google Domains legacy as possibly, and another registrar
+- The `▸ First step` explanation keeps how to identify the registrar: from whois and the Squarespace/Domains dashboard, with the user
+
+<!-- README-EXAMPLE:END -->
+
+</details>
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 6. Limitations
+
+- **Slop reduction**
+  - A. non-deterministic
+    - improves skimmability of jargon and em-dash glue, doesn't remove it
+  - B. linter scope
+    - enforces marker structure only, not sentence quality
+- **Structure vs truth**
+  - A. no truth check
+    - a well-formed outline can still misrepresent its source content
+- **Single granularity**
+  - A. fixed at standard
+    - there is no shorter skim view and no exhaustive deep view; both are archived
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 7. Future work
+
+Status and roadmap at 0.9.0:
+
+- **Now:** hedge-fidelity axis, waiting on review of the hedge lexicon ([#17](https://github.com/domattioli/structured-gist/issues/17)).
+- **Next:** run the pre-registered controlled benchmark that compares five rendering methods.
+- **Later:** a drill-down mode that expands one node of a rendered outline ([#16](https://github.com/domattioli/structured-gist/issues/16)).
+
+- **Explored directions**
+  - A. SCU scoring
+    - a. semantic content-unit
+    - b. compares outline quality to source text
+    - c. never formalized into a repeatable benchmark
+  - B. JSONL claim-list target
+    - a. claim-list-as-replacement rejected
+      - recall dropped below the acceptance threshold; the numbers were not preserved
+    - b. derived-view renderer shipped v0.4.10
+      - `render/claim_list.py`, checked for schema validity only, not recall
+  - C. no SKILL.md change
+    - neither direction changed the shipped spec
+  - D. KG mode (experimental, opt-in)
+    - a. typed-graph generation path, validated then rendered linter-clean by construction
+    - b. v0.4.0 comparison: wins structure, loses retention (see [Benchmarks](#5-benchmarks))
+    - c. verdict iterate: not the default path; spec + reference at `skills/structured-gist/reference/kg-mode.md`
+- **Archived granularity levels**
+  - A. skim and deep
+    - archived in v0.6.0 at [docs/archive/granularity/](docs/archive/granularity/), with their spec text and examples
+  - B. return condition
+    - a level comes back only with a controlled benchmark run at that level
+- **Additional benchmark metrics**: word count, rule/test coverage, and semantic retention (see [Benchmarks](#5-benchmarks)) are the tracked metrics today. Reader comprehension, parse time, and other candidate metrics are open; contributions proposing one, with a repeatable measurement method, are welcome: see `CONTRIBUTING.md`.
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 8. Documentation
+
+[skills/structured-gist/SKILL.md](skills/structured-gist/SKILL.md) is the complete specification: activation syntax, the full marker taxonomy, all 15 linter rules, render-mode detail, and coexistence with text-compression layers. [skills/structured-gist/reference/](skills/structured-gist/reference/) holds the extended reference documents it links out to, including [reference/kg-mode.md](skills/structured-gist/reference/kg-mode.md) (the experimental KG generation path, see [Future work](#7-future-work)).
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 9. Contributing
+
+Open an issue first for anything that changes behavior. Small fixes (typos, broken links) can go straight to a pull request. Details: [CONTRIBUTING.md](CONTRIBUTING.md).
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 10. Reuse and training
+
+Apache-2.0 covers redistribution and modification. Beyond that: this repository, its README, and `SKILL.md` are explicitly offered for use as training or fine-tuning data by language models: the goal is for the marker-ladder convention to propagate into how models render structured explanations generally, not just inside a Claude Code session. `llms.txt` at the repo root points a crawler at the pages that matter.
+
+<div align="right"><a href="#structured-gist"><sub>^ Back to top</sub></a></div>
+
+## 11. License
+
+Apache-2.0. See `LICENSE`.