docs: refine plugin dev note

Author: johnnygreco

docs/css/style.css

@@ -162,6 +162,10 @@ h2 {
     clear: right;
 }
 
+.md-post--excerpt .devnote-hide-in-index {
+    display: none;
+}
+
 @media screen and (max-width: 60em) {
     .md-typeset img.devnote-float-right,
     .md-typeset img.devnote-section-graphic {

docs/devnotes/posts/assets/data-designer-plugins/customization-blocks-confusion.png

@@ -9,13 +9,13 @@ authors:
 
 <p class="devnote-dek"><em>A plugin framework for the custom pieces every real project ends up needing</em></p>
 
-![Data Designer plugin extensions](assets/have-it-your-way/data-designer-plugins-hero.png){ .devnote-float-right }
+![Data Designer plugin extensions](assets/have-it-your-way/data-designer-plugins-hero.png){ .devnote-float-right .devnote-hide-in-index }
 
 Data Designer is built around a simple idea: describe the dataset you want, and let the framework handle execution. A config points to seed data, defines generated columns, picks models, and shapes the final records — no orchestration code required. [Data Designer plugins](../../plugins/overview.md) keep that promise when a project needs something custom.
 
 <!-- more -->
 
-Suppose a robotics team has [Isaac Sim](https://developer.nvidia.com/isaac/sim)-generated warehouse runs and wants to turn robot poses, camera views, and event metadata into instruction data. With an internal simulation-log plugin, the user-facing part can still be this small:
+What does "something custom" actually look like? Picture a robotics team sitting on a pile of [Isaac Sim](https://developer.nvidia.com/isaac/sim)-generated warehouse runs, trying to turn robot poses, camera views, and event metadata into instruction data. With an internal simulation-log plugin, the user-facing part can still be this small:
 
 ```bash
 uv pip install data-designer-isaac-logs
@@ -26,40 +26,25 @@ from data_designer_isaac_logs.config import IsaacRunSeedSource
 from data_designer_isaac_logs.config import WarehouseEventLabelColumnConfig
 from data_designer_isaac_logs.config import RobotSFTProcessor
 
-builder.with_seed_dataset(
+config_builder.with_seed_dataset(
     IsaacRunSeedSource(
         run_dir="s3://warehouse-sim/rare-events/",
         streams=("robot_pose", "overhead_rgb", "event_log"),
         max_events=10_000,
     )
 )
-builder.add_column(
+config_builder.add_column(
     WarehouseEventLabelColumnConfig(
         name="safety_instruction",
         pose_column="robot_pose",
         event_log_column="event_log",
     )
 )
-builder.add_processor(RobotSFTProcessor(output_column="messages"))
+config_builder.add_processor(RobotSFTProcessor(output_column="messages"))
 ```
 
 That is the point of plugins: install a package, import its config classes, and keep the workflow declarative. The Isaac run reader, event labeler, and trainer-format processor own the custom parsing, labeling, validation, and export shape, while Data Designer still handles discovery, dependency ordering, model calls, previews, and output.
 
-
-<div class="devnote-clear"></div>
-
-!!! tip "TL;DR - What plugins give you"
-
-    1. Plugins expose custom behavior through the same Data Designer config and runtime paths as built-in components.
-
-    2. A plugin is a Python package discovered through the `data_designer.plugins` entry point group. Once installed, there is no manual registration step in user code.
-
-    3. Plugin configs use the same typed config model and serialization behavior as core config types. The engine receives an implementation through the plugin registry.
-
-    4. Plugins can start as a local editable install, move to an internal package index, and later be published publicly.
-
-    5. NVIDIA-maintained plugins now live in [NVIDIA-NeMo/DataDesignerPlugins](https://github.com/NVIDIA-NeMo/DataDesignerPlugins), separate from the core repo and installed as packages.
-
 ---
 
 ## **Customization Is the Normal Case**
@@ -68,7 +53,7 @@ That is the point of plugins: install a package, import its config classes, and
 
 The mess usually starts innocently. A team defines a Data Designer config, then discovers that its seed data lives in an internal layout, its generated column needs a domain simulator, and its trainer expects a slightly different record shape. Someone writes a small reader beside the notebook. Someone patches a generator into a project folder. Someone adds a cleanup script after preview because the final export has one more organization-specific rule. Each choice is reasonable because every project has its own corpus, policy, ontology, simulator, and training stack.
 
-The problem is that the custom behavior now lives around Data Designer instead of inside the Data Designer workflow. It is harder to validate, harder to share, harder to version, and easier to lose. Plugins give that bespoke work a clean package boundary: a name, typed config, runtime implementation, entry point, and tests that travel together. Users still declare the dataset they want, but the local reader, domain generator, or trainer-format processor becomes a normal Data Designer component instead of another layer of glue.
+The problem is that the custom behavior now lives around Data Designer instead of inside the Data Designer workflow. It is harder to validate, harder to share, harder to version, and easier to lose. Plugins give that bespoke work a clean package boundary – a name, typed config, runtime implementation, entry point, and tests that travel together. Users still declare the dataset they want, but the local reader, domain generator, or trainer-format processor becomes a normal Data Designer component instead of another layer of glue.
 
 <div class="devnote-clear"></div>
 
@@ -96,12 +81,29 @@ These boundaries are intentionally narrow. A plugin should own the behavior that
 
 Consider a markdown seed reader. The one-off version might be a helper function that walks a directory, splits files into sections, returns a DataFrame, and then gets copied into the next project that needs it. That can work for one project. It becomes a problem when the reader needs options, tests, documentation, versioning, or reuse across teams. At that point, the helper has become a capability whether or not it is packaged like one.
 
-A plugin packages the same idea as a small Python project:
+A plugin packages that same helper as a small Python project:
 
 - A user-facing config class describes the options.
 - An implementation class does the work.
 - A `Plugin` object connects the config to the implementation.
-- A Python entry point exposes the plugin to Data Designer.
+- An entry point registers the plugin with Data Designer.
+
+The config class declares the user-facing options. For a directory-backed reader, Data Designer's `FileSystemSeedSource` already has fields for `path`, `file_pattern`, and `recursive`, we just need to define the seed type discriminator:
+
+```python
+# config.py
+from __future__ import annotations
+
+from typing import Literal
+
+from data_designer.config.seed_source import FileSystemSeedSource
+
+
+class MarkdownSectionSeedSource(FileSystemSeedSource):
+    """Configure the markdown sections seed reader."""
+
+    seed_type: Literal["markdown-sections"] = "markdown-sections"
+```
 
 The implementation class is where the old helper code should move. For a filesystem seed reader, Data Designer gives you a small interface instead of a blank page: implement `build_manifest(...)` to build a cheap index of candidate inputs, and implement `hydrate_row(...)` to turn each selected manifest row into one or more dataset rows. That split matters because Data Designer can sample, shuffle, partition, and batch against the lightweight manifest before paying the cost of reading files, parsing sections, or calling project-specific libraries. The parser can still be a normal helper function; the reader class is the framework boundary.
 
@@ -173,17 +175,9 @@ class MarkdownSectionSeedReader(FileSystemSeedReader[MarkdownSectionSeedSource])
         ]
 ```
 
-The class should own only the domain-specific behavior: how to find candidate files, how to parse them, and what rows it emits. Let Data Designer keep owning attachment, sampling, shuffling, batching, DuckDB registration, dependency resolution, and execution. The same rule applies to column generators and processors: choose the closest base class, keep options on the config object, implement the narrow runtime method, and leave orchestration out of the plugin.
+The same rule applies to column generators and processors: choose the closest base class, keep options on the config object, implement the narrow runtime method, and leave orchestration out of the plugin.
 
-The entry point exposes the plugin package to Data Designer:
-
-```toml
-# pyproject.toml
-[project.entry-points."data_designer.plugins"]
-markdown-sections = "data_designer_markdown_sections.plugin:plugin"
-```
-
-The plugin object tells Data Designer what kind of extension this is and where to find the config and implementation:
+Two small files connect the plugin to Data Designer — a `Plugin` descriptor that names the config and implementation, and a Python entry point that exposes them at install time:
 
 ```python
 # plugin.py
@@ -196,6 +190,12 @@ plugin = Plugin(
 )
 ```
 
+```toml
+# pyproject.toml
+[project.entry-points."data_designer.plugins"]
+markdown-sections = "data_designer_markdown_sections.plugin:plugin"
+```
+
 After that, users do not import engine internals or run registration code. They import the config class and use it:
 
 ```python
@@ -221,7 +221,7 @@ builder.add_column(
 results = DataDesigner().preview(builder, num_records=5)
 ```
 
-No custom orchestration. No separate DataFrame preparation step. The reader is part of the Data Designer workflow. For the same package shape applied to other extension points, see the [Build Your Own plugin guide](../../plugins/build_your_own.md#implementation-patterns), [Column Generators](../../code_reference/engine/column_generators.md), and [Engine Processors](../../code_reference/engine/processors.md) documentation.
+No custom orchestration. No separate DataFrame preparation step. The reader is part of the Data Designer workflow.
 
 ---
 
@@ -243,34 +243,22 @@ It is useful for the broader community too. If you build a plugin that should be
 
 ## **A Repository for First-Party Plugins**
 
-We also created [NVIDIA-NeMo/DataDesignerPlugins](https://github.com/NVIDIA-NeMo/DataDesignerPlugins), a dedicated repository for NVIDIA-maintained plugins. It is where we will publish first-party plugin packages, recommended packaging examples, and plugin-specific docs as the catalog grows.
+We recently created [NVIDIA-NeMo/DataDesignerPlugins](https://github.com/NVIDIA-NeMo/DataDesignerPlugins), a dedicated repository for NVIDIA-maintained plugins. It is where we will publish first-party plugin packages, recommended packaging examples, and plugin-specific docs as the catalog grows.
 
 The split keeps the core Data Designer repo focused on the framework: the config API, engine execution, model integration, validation behavior, and stable plugin interface. Plugin packages can depend on optional libraries, target narrower use cases, and move at a different release pace, while still installing separately and using the same plugin interface once installed.
 
 ---
 
-## **Start with One Capability**
-
-If you have custom Data Designer code that keeps getting copied between projects, it is a strong candidate for a plugin.
-
-Pick one capability. Give it a typed config. Write the implementation behind the matching plugin boundary. Add an `assert_valid_plugin(...)` test so structural problems fail early:
-
-```python
-from data_designer.engine.testing import assert_valid_plugin
-from data_designer_markdown_sections.plugin import plugin
-
-assert_valid_plugin(plugin)
-```
-
-Then run a tiny `preview` before you trust it in a larger generation job.
+## **Where to Go Next**
 
-For implementation details, see:
+Interested in building your own plugin? Here are some resources to get you started:
 
-- [Plugins overview](../../plugins/overview.md)
-- [Build Your Own](../../plugins/build_your_own.md)
-- [Using Models in Plugins](../../plugins/models.md)
-- [Available Plugins](../../plugins/available.md)
-- [Markdown Section Seed Reader recipe](../../recipes/plugin_development/markdown_seed_reader.md)
+1. [Plugins overview](../../plugins/overview.md) — learn how plugins fit into Data Designer
+2. [Build Your Own](../../plugins/build_your_own.md) — follow the authoring guide for seed readers, column generators, and processors
+3. [Using Models in Plugins](../../plugins/models.md) — call configured models from plugin code
+4. [Markdown Section Seed Reader recipe](../../recipes/plugin_development/markdown_seed_reader.md) — study the complete version of the example from this post
+5. [Available Plugins](../../plugins/available.md) — browse the catalog and learn how to submit your own plugin
+6. [DataDesignerPlugins on GitHub](https://github.com/NVIDIA-NeMo/DataDesignerPlugins) — explore first-party plugin packages
 
 Moving plugins out of experimental mode means Data Designer no longer has to predict every customization users will need. The framework provides the pipeline. Plugins supply the custom pieces.