docs: #978 - [M3-P4] Update Documentation and Create M4 Follow-up Issue

[Gorkowski]

Target Branch: main

Fixes #978 | Workflow: 2b58aa9a

Summary

Completes Phase 4 (final phase) of the M3 Jupytext Pilot Migration by updating documentation to reflect the Jupytext paired sync workflow. This adds notebook editing guidance to AGENTS.md, marks the M3 maintenance plan as "Shipped", and creates the M4 follow-up issue (#979) for migrating the remaining ~35 notebooks.

What Changed

Modified Components

• AGENTS.md - Added new "Notebook Editing (Jupytext Paired Sync)" section after the "Quick Checks" section with a concise 5-step workflow guide and key points. Updated "Last Updated" date to 2026-01-30.

• adw-docs/dev-plans/maintenance/M3-jupytext-notebook-sync.md - Updated M3 maintenance plan:

  • Changed status from "Planning" to "Shipped"
  • Filled in issue numbers for all 4 phases (P1:[M3-P1] Configure Jupytext Paired Sync for Pilot Notebooks #975, P2:[M3-P2] Convert Pilot Notebooks to Jupytext Paired Format #976, P3:[M3-P3] Validate Jupytext Workflow and Execute Pilot Notebooks #977, P4:[M3-P4] Update Documentation and Create M4 Follow-up Issue #978)
  • Marked all phase tasks as complete
  • Added completion entry to Change Log
  • Updated Future Work section with M4 issue link (fix: #975 - [M3-P1] Configure Jupytext Paired Sync for Pilot Notebooks #979)

How It Works

This is a documentation-only change with no code modifications. The workflow documented in AGENTS.md follows this pattern:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Edit .py   │────▶│  Lint .py   │────▶│    Sync     │────▶│   Execute   │────▶│   Commit    │
│   file      │     │   (ruff)    │     │  (jupytext) │     │  (validate) │     │ both files  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
        │                  │                   │                   │                   │
        ▼                  ▼                   ▼                   ▼                   ▼
   percent format     catch syntax      update .ipynb       generate outputs     keep paired
   with # %% cells      errors           from .py            for website          .py + .ipynb

Key workflow principles:

• Always edit .py files, not .ipynb directly
• Lint before sync to catch syntax errors early
• Execute after sync to validate code and generate website outputs
• Commit both files to keep them paired

Implementation Notes

• M4 Follow-up Issue: Created issue fix: #975 - [M3-P1] Configure Jupytext Paired Sync for Pilot Notebooks #979 for migrating remaining ~35 notebooks outside the pilot scope (Activity/ and Gas_Phase/)
• AGENTS.md placement: New section placed between "Quick Checks" and "Getting Help" sections for logical flow
• Documentation reference: Full Jupytext documentation exists in adw-docs/documentation_guide.md (lines 341-534)

Testing

• Manual verification: AGENTS.md markdown renders correctly
• Link validation: All references point to valid files and sections
• No code changes: This is documentation-only, no test suite impact

References

M3 Pilot Migration:

• [M3-P1] Configure Jupytext Paired Sync for Pilot Notebooks #975 - M3-P1: Configuration Files
• [M3-P2] Convert Pilot Notebooks to Jupytext Paired Format #976 - M3-P2: Convert Pilot Notebooks
• [M3-P3] Validate Jupytext Workflow and Execute Pilot Notebooks #977 - M3-P3: Workflow Validation
• [M3-P4] Update Documentation and Create M4 Follow-up Issue #978 - M3-P4: Documentation Update (this PR)

Follow-up Work:

• fix: #975 - [M3-P1] Configure Jupytext Paired Sync for Pilot Notebooks #979 - M4: Jupytext Full Migration - Remaining Notebooks

[Copilot]

Pull request overview

This PR completes Phase 4 (final phase) of the M3 Jupytext Pilot Migration by updating documentation to reflect the Jupytext paired sync workflow. It adds notebook editing guidance to AGENTS.md, marks the M3 maintenance plan as "Shipped", and documents the creation of M4 follow-up issue #979 for migrating the remaining notebooks.

Changes:

• Added "Notebook Editing (Jupytext Paired Sync)" section to AGENTS.md with a 5-step workflow guide for LLM agents
• Updated M3 maintenance plan status from "Planning" to "Shipped", filled in all phase issue numbers, and marked all tasks complete
• Added completion entry to the M3 plan's Change Log

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
AGENTS.md	Added new notebook editing workflow section after "Quick Checks" and updated the "Last Updated" date to 2026-01-30
adw-docs/dev-plans/maintenance/M3-jupytext-notebook-sync.md	Changed status to "Shipped", filled in issue numbers for all phases, marked all tasks complete, updated Change Log, and referenced M4 follow-up

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.