Fix documentation issues from review

Address gatecat's review comments on documentation:

- docs/using-pin-signatures.rst:
  * Fix I2C example to use OPEN_DRAIN_STRONG_DOWN (not STRONG_UP)
  * Add note linking to chipflow-examples for CPU/Wishbone examples

- docs/simulation-guide.rst:
  * Fix input.json format to use wait_for/action (not timestamps)
  * Update CXXRTL code to use cxxrtl::value (not wire)
  * Use .get()/.set() methods instead of .curr/.next
  * Retitle "Simulation Hangs" to "Incomplete Simulation Output"
  * Clarify that simulation always stops after num_steps

- docs/architecture.rst:
  * Add example showing how to attach simulation models to custom signatures

- docs/contributor-pin-signature-internals.rst:
  * Replace verbose "Summary" section with concise "Key Files" list
  * Remove redundant feature bullet points

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: robtaylor

docs/architecture.rst

@@ -428,6 +428,28 @@ Create new interface types:
                 "custom": Out(BidirIOSignature(4, **kwargs))
             })
 
+To attach a simulation model to your custom signature:
+
+.. code-block:: python
+
+    from chipflow_lib.platform import SimModel, BasicCxxBuilder
+
+    # Define the C++ model
+    MY_BUILDER = BasicCxxBuilder(
+        models=[
+            SimModel('my_custom', 'my_namespace', MyCustomSignature),
+        ],
+        hpp_files=[Path('design/sim/my_custom_model.h')],
+    )
+
+    # In your custom SimStep
+    class MySimPlatform(SimPlatform):
+        def __init__(self, config):
+            super().__init__(config)
+            self._builders.append(MY_BUILDER)
+
+See :doc:`simulation-guide` for complete examples of creating custom simulation models.
+
 Custom Steps
 ~~~~~~~~~~~~
 

docs/contributor-pin-signature-internals.rst

@@ -755,24 +755,14 @@ Pydantic's ``TypeAdapter`` provides:
 - Type hints for IDE support
 - Serialization to JSON-compatible Python dicts
 
-Summary
--------
-
-The ChipFlow annotation architecture provides:
-
-1. **Type-safe metadata** - Pydantic validates all annotations
-2. **JSON schema compatibility** - External tools can parse RTLIL annotations
-3. **Extensibility** - New annotation types via ``@amaranth_annotate``
-4. **Platform independence** - Same metadata consumed by silicon, simulation, software platforms
-5. **Compile-time validation** - Errors caught during elaboration, not during synthesis
-
-Key files to study:
+Key Files
+---------
 
 - ``chipflow_lib/platform/io/annotate.py`` - Core annotation infrastructure
 - ``chipflow_lib/platform/io/iosignature.py`` - I/O signature base classes
 - ``chipflow_lib/platform/io/signatures.py`` - Concrete signatures and decorators
-- ``chipflow_lib/platform/silicon.py`` - Silicon platform port creation
-- ``chipflow_lib/platform/software.py`` - Software platform extraction
+- ``chipflow_lib/platform/silicon.py`` - Silicon platform consumption
+- ``chipflow_lib/platform/software.py`` - Software platform consumption
 - ``chipflow_lib/software/soft_gen.py`` - Code generation
 
 See Also

docs/platform-api.rst

@@ -156,9 +156,9 @@ Utility Functions
 
 .. autofunction:: chipflow_lib.platform.base.setup_amaranth_tools
 
-.. autofunction:: chipflow_lib.platform.utils.top_components
+.. autofunction:: chipflow_lib.utils.top_components
 
-.. autofunction:: chipflow_lib.platform.utils.get_software_builds
+.. autofunction:: chipflow_lib.utils.get_software_builds
 
 Constants
 ---------

docs/simulation-guide.rst

@@ -345,7 +345,7 @@ Creating Reference
 Input Commands (Optional)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can provide input commands via ``design/tests/input.json``:
+You can provide input commands via ``design/tests/input.json``. To reduce test churn from timing changes, input files use output events as triggers rather than timestamps:
 
 .. code-block:: json
 
@@ -362,7 +362,7 @@ Commands are processed sequentially:
 - ``action`` commands queue an action (like transmitting data) for a peripheral
 - ``wait`` commands pause execution until the specified event occurs
 
-Models process these commands at the specified timestamps.
+See the `mcu_soc example <https://github.com/ChipFlow/chipflow-examples/blob/main/mcu_soc/design/tests/input.json>`_ for a working input.json file.
 
 Customizing Simulation
 ----------------------
@@ -385,18 +385,18 @@ To add a custom peripheral model:
 
        template<size_t WIDTH>
        class my_peripheral_model {
-           cxxrtl::wire<WIDTH>& output;
-           cxxrtl::wire<WIDTH>& input;
+           cxxrtl::value<WIDTH>& output;
+           cxxrtl::value<WIDTH>& input;
 
        public:
            my_peripheral_model(const char* name,
-                             cxxrtl::wire<WIDTH>& o,
-                             cxxrtl::wire<WIDTH>& i)
+                             cxxrtl::value<WIDTH>& o,
+                             cxxrtl::value<WIDTH>& i)
                : output(o), input(i) {}
 
            void step(unsigned timestamp) {
-               // Model behavior
-               input.next = output.curr;
+               // Model behavior - use .get() for reading, .set() for writing
+               input.set(output.get());
            }
        };
 
@@ -448,19 +448,23 @@ Performance Tips
 Common Issues
 -------------
 
-Simulation Hangs
-~~~~~~~~~~~~~~~~
+Incomplete Simulation Output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Symptom**: Simulation completes but expected operations are incomplete
 
-**Symptom**: Simulation runs but never finishes
+**Note**: The simulation will always stop after ``num_steps`` clock cycles, regardless of what the design or software is doing. If your firmware hasn't completed by then, you'll see incomplete output.
 
 **Causes**:
+- ``num_steps`` too low for the operations being performed
 - Firmware stuck in infinite loop
 - Waiting for peripheral that never responds
 
 **Solutions**:
-- Reduce ``num_steps`` to see how far it gets
-- Enable ``DEBUG=1`` and attach debugger
-- Add timeout checks in your firmware
+- Increase ``num_steps`` in chipflow.toml if legitimate operations need more time
+- Enable ``DEBUG=1`` and attach debugger to see where execution is stuck
+- Add timeout checks in your firmware to detect hangs
+- Use event logging to see how far the simulation progressed
 
 No UART Output
 ~~~~~~~~~~~~~~

docs/using-pin-signatures.rst

@@ -111,11 +111,11 @@ For Sky130 chips, you can configure the I/O cell drive mode:
 
     from chipflow_lib.platforms import Sky130DriveMode, GPIOSignature
 
-    # Use open-drain with strong pull-up for I2C
+    # Use open-drain with strong pull-down for I2C
     super().__init__({
         "i2c_gpio": Out(GPIOSignature(
             pin_count=2,
-            sky130_drive_mode=Sky130DriveMode.OPEN_DRAIN_STRONG_UP
+            sky130_drive_mode=Sky130DriveMode.OPEN_DRAIN_STRONG_DOWN
         ))
     })
 
@@ -395,8 +395,11 @@ Here's a complete working example combining all concepts:
 
             return m
 
+**Note:** For more advanced examples including CPU cores and Wishbone bus integration, see the `chipflow-examples repository <https://github.com/ChipFlow/chipflow-examples>`_, which contains tested and working SoC designs.
+
 See Also
 --------
 
 - :doc:`chipflow-toml-guide` - Configuring your ChipFlow project
 - :doc:`platform-api` - Complete platform API including SimPlatform and attach_data
+- `ChipFlow Examples <https://github.com/ChipFlow/chipflow-examples>`_ - Complete working examples with CPU and Wishbone bus