TheAcharya · IAmVigneswaran · Jul 18, 2026 · Jul 18, 2026 · Jul 18, 2026
diff --git a/.cursorrules b/.cursorrules
diff --git a/.gitignore b/.gitignore
@@ -22,11 +22,14 @@ Package.resolved
 # Xcode
 xcuserdata/
 
-# Local Excel report integration fixture and generated workbooks (not committed).
-Tests/ExcelReportTest/Sample.fcpxmld/
-Tests/ExcelReportTest/Sample.fcpxml
+# Local Excel report integration fixtures and generated workbooks (not committed).
+Tests/ExcelReportTest/*.fcpxmld/
+Tests/ExcelReportTest/*.fcpxml
+Tests/ExcelReportTest/Output/*.fcpxmld/
+Tests/ExcelReportTest/Output/*.fcpxml
 Tests/ExcelReportTest/Output/*.xlsx
 Tests/ExcelReportTest/Output/*.pdf
+Tests/ExcelReportTest/Output/~$*
 
 # Private user-submitted FCPXML inbox (never commit contents — only README / .gitkeep).
 Tests/Submitted FCPXML/Inbox/**

diff --git a/AGENT.md b/AGENT.md
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,8 +7,27 @@ OpenFCPXMLKit uses **New Features**, **Improvements**, and **Bug Fixes** for eac
 
 ---
 
+## [3.1.1](https://github.com/TheAcharya/OpenFCPXMLKit/releases/tag/3.1.1) - 2026-07-18
+
+### ✨ New Features
+
+- **Markers outside clip boundaries:** By default the Markers report omits markers whose `start` is outside the host clip’s media range (hidden in Final Cut Pro’s timeline/Tags). Opt in with `ReportOptions.includeMarkersOutsideClipBoundaries` / CLI `--include-markers-outside-clip-boundaries` to include them and add a **Hidden** column (✓ outside / ✗ inside). The Hidden column is not part of `--exclude-column`. Sample: `HiddenMarkers.fcpxml`. Tests: `FCPXMLMarkersReportTests`, `FCPXMLFileTest_HiddenMarkers`; ExcelReportTest writes `OFK-OutsideClipBoundaries.xlsx` / `.pdf`.
+- **Excel sheet protection:** `ReportOptions.protectSheets` / CLI `--protect-sheets` applies worksheet protection to every sheet in the Excel workbook (cover + content). Edit lock only — not file-open encryption; PDF export is unchanged (use Preview → Encrypt for PDF passwords). Tests: `FCPXMLReportExcelExportTests`; ExcelReportTest writes `OFK-ProtectedSheets.xlsx`.
+
+### 🔧 Improvements
+
+- **Documentation:** Added [GUARDRAILS.md](GUARDRAILS.md) as a companion to [ARCHITECTURE.md](ARCHITECTURE.md) — hard must / must-not constraints for contributors and agents (layer boundaries, naming, FCPXML 1.5 floor, reporting honesty, fixtures, Signs for learned locks). Cross-linked from README, Manual index, CONTRIBUTING, AGENT, and `.cursorrules`.
+- **Documentation sync:** Test/sample counts and API surface refreshed across README, Manual, Tests READMEs, ARCHITECTURE (incl. Mermaid), AGENT, `.cursorrules`, and GUARDRAILS — **1084** listed tests (**1078** + **6**), **60** public FCPXML samples; documenting `includeMarkersOutsideClipBoundaries` / `--protect-sheets`. Manual chapters **19** / **16** / **17** / **12** / **01** / **20** aligned for `protectSheets`, Markers **Hidden** vs `hidden-clip-marker`, and Excel-only sheet protection.
+
+### 🐛 Bug Fixes
+
+- None in this release.
+
+---
+
 ## [3.1.0](https://github.com/TheAcharya/OpenFCPXMLKit/releases/tag/3.1.0) - 2026-07-16
 
+
 ### ✨ New Features
 
 - **Effects → Projection:** Report builder prefers ``WindowReportEffectAnnotation`` collected during timeline Projection via shared ``EffectsCollector`` (filters, volume/implicit volume, transform rows, compositing, spatial conform; video-filter occlusion policy preserved). Extraction remains fallback when Projection has no effect annotations. Tests: `FCPXMLEffectsProjectionTests`.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,6 +2,8 @@
 
 Please note that this project is not under active or regular development, so response times to pull requests may be slow. The codebase is also highly complex, so please take time to understand its structure and logic before proposing changes.
 
+Before opening a PR, read **[ARCHITECTURE.md](ARCHITECTURE.md)** (how the system is shaped) and **[GUARDRAILS.md](GUARDRAILS.md)** (must / must-not constraints — layer boundaries, naming, tests, FCPXML compatibility).
+
 We appreciate your input! If you'd like to contribute, whether by:
 
 - Submitting a fix

diff --git a/Documentation/Manual/00-Index.md b/Documentation/Manual/00-Index.md
@@ -27,13 +27,15 @@ Complete manual and usage guide for **OpenFCPXMLKit**, a Swift 6 framework for F
 | [16 — CLI](16-CLI.md) | Experimental command-line interface (OpenFCPXMLKit-CLI) |
 | [17 — Examples](17-Examples.md) | End-to-end workflows and code examples |
 | [18 — Cross-Platform & iOS](18-Cross-Platform-iOS.md) | XML abstraction layer, OFKXML protocols, Foundation vs AEXML backends, iOS support |
-| [19 — Reporting, Excel & PDF Export](19-Reporting.md) | Report builder, ReportOptions (`mediaResolutionPolicy`, `copyrightLabel`, …), ReportTimecodeFormat, ReportBuildPhase (incl. projecting), report sections, universal **Row**, Projection-first Markers/Keywords/Titles/Transitions/Effects, XLKit Excel + CoreGraphics PDF |
+| [19 — Reporting, Excel & PDF Export](19-Reporting.md) | Report builder, ReportOptions (`mediaResolutionPolicy`, `copyrightLabel`, `includeMarkersOutsideClipBoundaries`, `protectSheets`, …), ReportTimecodeFormat, ReportBuildPhase (incl. projecting), report sections, universal **Row**, Projection-first Markers/Keywords/Titles/Transitions/Effects, XLKit Excel + CoreGraphics PDF |
 
 ---
 
 ## Quick links
 
 - **Project README:** [../README.md](../README.md) (repository root)
+- **Architecture:** [../ARCHITECTURE.md](../ARCHITECTURE.md) — layers and codebase map
+- **Guardrails:** [../GUARDRAILS.md](../GUARDRAILS.md) — must / must-not for contributors and agents
 - **CLI reference:** [../Sources/OpenFCPXMLKitCLI/README.md](../Sources/OpenFCPXMLKitCLI/README.md)
 - **Tests:** [../Tests/README.md](../Tests/README.md) — suite layout; [Submitted FCPXML](../Tests/Submitted%20FCPXML/README.md) for private local investigation (never commit private FCPXML)
 - **FCPXML reference:** [fcp.cafe/developers/fcpxml](https://fcp.cafe/developers/fcpxml)
diff --git a/Documentation/Manual/01-Overview.md b/Documentation/Manual/01-Overview.md
@@ -50,7 +50,7 @@ All core behaviour is defined by **protocols** with both sync and async APIs. De
 
 Semantic validators (`FCPXMLValidator`, `FCPXMLDTDValidator`, `FCPXMLStructuralValidator`) are injectable concrete types, not protocol-backed.
 
-**Layer stack (bottom → top):** XML → Parsing → Model → Extraction → **Projection** → Reporting. Extend lower layers before adding report-only XML walks. See [20 — Timeline Projection](20-Timeline-Projection.md) and [ARCHITECTURE.md](../../ARCHITECTURE.md) §2.7.
+**Layer stack (bottom → top):** XML → Parsing → Model → Extraction → **Projection** → Reporting. Extend lower layers before adding report-only XML walks. See [20 — Timeline Projection](20-Timeline-Projection.md), [ARCHITECTURE.md](../../ARCHITECTURE.md) §2.7, and [GUARDRAILS.md](../../GUARDRAILS.md) for must / must-not constraints.
 
 ## Logging
 

diff --git a/Documentation/Manual/12-Typed-Models.md b/Documentation/Manual/12-Typed-Models.md
@@ -152,6 +152,8 @@ let marker = FinalCutPro.FCPXML.HiddenClipMarker()
 // Add to clip via fcpxAnnotations / addToClip(annotationElements:)
 ```
 
+Do **not** confuse this DTD element with the Markers **report** concept of “Hidden”: report **Hidden** means a normal `marker` / `chapter-marker` whose `start` is outside the host clip’s media range (omitted by default; opt in with `includeMarkersOutsideClipBoundaries` / `--include-markers-outside-clip-boundaries`). See [19 — Reporting](19-Reporting.md#markers).
+
 ---
 
 ## Format and Asset (1.13+)

diff --git a/Documentation/Manual/16-CLI.md b/Documentation/Manual/16-CLI.md
@@ -15,7 +15,7 @@ The package includes an experimental command-line tool **OpenFCPXMLKit-CLI**. It
 
 ## Commands and options
 
-Use **one** of: `--check-version`, `--convert-version`, `--validate`, `--media-copy`, `--report`, or `--create-project`. For `--convert-version`, `--media-copy`, `--report` (and default process), `<output-dir>` is required and is **created if missing**. For `--create-project`, the single positional argument is `<output-dir>` (also created if missing). `--extension-type` requires `--convert-version`. REPORT modifiers (`--report-full`, section flags, `--timecode-format`, `--media-resolution`, etc.) require `--report`.
+Use **one** of: `--check-version`, `--convert-version`, `--validate`, `--media-copy`, `--report`, or `--create-project`. For `--convert-version`, `--media-copy`, `--report` (and default process), `<output-dir>` is required and is **created if missing**. For `--create-project`, the single positional argument is `<output-dir>` (also created if missing). `--extension-type` requires `--convert-version`. REPORT modifiers (`--report-full`, section flags, `--include-markers-outside-clip-boundaries`, `--protect-sheets`, `--timecode-format`, `--media-resolution`, `--label-copyright`, `--create-pdf`, etc.) require `--report`.
 
 ### GENERAL
 
@@ -50,6 +50,8 @@ Build an Excel (`.xlsx`) report workbook from FCPXML/FCPXMLD, with optional PDF
 | **--label-copyright &lt;text&gt;** | Optional copyright / attribution line (with `--report`). Excel cover sheet **A2** below Created-by; PDF cover below Created-by (same subtitle font/size); PDF running footer centre (same footer font/size). |
 | **--exclude-role &lt;role&gt;** | Exclude a role or subrole from the role inventory (repeatable). Excluding a main role also excludes its subroles. |
 | **--exclude-disabled-clips** | Omit disabled clips (`enabled="0"`) from all timeline-based report sections (with `--report`). |
+| **--include-markers-outside-clip-boundaries** | Include markers outside the host clip’s media range (hidden in FCP Tags/timeline) and add a **Hidden** column (✓/✗) on the Markers sheet (with `--report`). Default omits those markers. Not available via `--exclude-column`. |
+| **--protect-sheets** | Protect every sheet in the Excel workbook against casual edits (with `--report`). Cover + all content sheets. **Edit lock only** — not file-open encryption; Excel still opens freely and protection can be turned off. PDF export is unaffected (use Preview → Encrypt for a PDF open password). |
 | **--exclude-column &lt;column&gt;** | Exclude a workbook column from every applicable report sheet (repeatable; with `--report`). |
 | **--timecode-format &lt;format&gt;** | Timeline time display format for report cells in Excel and PDF (with `--report`). Values: `HH:MM:SS:FF` (default; SMPTE with frames, `;` before frames for drop-frame), `Frames`, `Feet+Frames`, `HH:MM:SS`. |
 
@@ -75,6 +77,23 @@ All REPORT flags except `--report` itself require `--report`.
 OpenFCPXMLKit-CLI --report --exclude-role Music --exclude-role Dialogue --exclude-role "SRT ▸ de-DE" /path/to/project.fcpxmld /path/to/output-dir
 ```
 
+#### Markers outside clip boundaries
+
+`--include-markers-outside-clip-boundaries` is a **boolean flag** (no value). By default the Markers sheet matches Final Cut Pro’s Tags list: markers whose `start` is outside the host clip’s media range are omitted and no **Hidden** column is shown. Pass the flag to include those markers and append **Hidden** (✓ = outside bounds, ✗ = inside). The Hidden column cannot be removed with `--exclude-column`.
+
+```bash
+OpenFCPXMLKit-CLI --report --report-markers --include-markers-outside-clip-boundaries \
+  /path/to/project.fcpxmld /path/to/output-dir
+```
+
+#### Excel sheet protection
+
+`--protect-sheets` is a **boolean flag** (no value). When set, every worksheet in the exported `.xlsx` (cover and content) gets XLKit sheet protection so casual cell edits are blocked. This is **not** workbook encryption: anyone can open the file, and Excel can remove protection without a password. PDF export ignores this flag — use macOS Preview’s **Encrypt** command if you need a PDF open password.
+
+```bash
+OpenFCPXMLKit-CLI --report --protect-sheets /path/to/project.fcpxmld /path/to/output-dir
+```
+
 #### Disabled clip exclusion
 
 `--exclude-disabled-clips` is a **boolean flag** (no value). Add it to any `--report` command to omit clips with `enabled="0"` from role inventory, markers, keywords, titles, transitions, effects, speed-change effects, and summary role durations.

diff --git a/Documentation/Manual/17-Examples.md b/Documentation/Manual/17-Examples.md
@@ -287,6 +287,23 @@ let report = try await fcpxml.buildReport(options: options)
 // Excel cover A2 + PDF cover/footer centre
 ```
 
+Markers outside clip boundaries + Excel sheet protection:
+
+```swift
+var options = FinalCutPro.FCPXML.ReportOptions.markersOnly
+options.includeMarkersOutsideClipBoundaries = true  // Hidden column (✓/✗)
+options.protectSheets = true                        // Excel edit lock (not encryption)
+let report = try await fcpxml.buildReport(options: options)
+try await FinalCutPro.FCPXML.ReportExcelExport.export(report, to: xlsxURL)
+```
+
+```bash
+OpenFCPXMLKit-CLI --report --report-markers \
+  --include-markers-outside-clip-boundaries \
+  --protect-sheets \
+  /path/to/project.fcpxmld /path/to/output-dir
+```
+
 ---
 
 ## Project a timeline (MediaUsageWindow)
-Original file line number
+Diff line change
@@ Expand Up / @@ -152,6 +152,8 @@ let marker = FinalCutPro.FCPXML.HiddenClipMarker() @@
     // Add to clip via fcpxAnnotations / addToClip(annotationElements:)
     ```
+    Do **not** confuse this DTD element with the Markers **report** concept of “Hidden”: report **Hidden** means a normal `marker` / `chapter-marker` whose `start` is outside the host clip’s media range (omitted by default; opt in with `includeMarkersOutsideClipBoundaries` / `--include-markers-outside-clip-boundaries`). See [19 — Reporting](19-Reporting.md#markers).
     ---
     ## Format and Asset (1.13+)
@@ Expand Down @@