SoundBlaster · SoundBlaster · Nov 21, 2025 · Nov 19, 2025 · Nov 19, 2025 · Nov 19, 2025
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,85 @@
+name: Deploy DocC Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch: # Allow manual trigger
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: macos-14
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Xcode
+        uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: latest-stable
+
+      - name: Build Documentation
+        run: |
+          swift package --allow-writing-to-directory ./docs \
+            generate-documentation \
+            --target SpecificationCore \
+            --output-path ./docs \
+            --transform-for-static-hosting \
+            --hosting-base-path SpecificationCore
+
+      - name: Add .nojekyll and index.html redirect
+        run: |
+          touch docs/.nojekyll
+          cat > docs/index.html << 'EOF'
+          <!DOCTYPE html>
+          <html>
+          <head>
+            <meta charset="utf-8">
+            <title>Redirecting to SpecificationCore Documentation</title>
+            <meta http-equiv="refresh" content="0; url=./documentation/specificationcore/">
+            <link rel="canonical" href="./documentation/specificationcore/">
+          </head>
+          <body>
+            <p>Redirecting to <a href="./documentation/specificationcore/">SpecificationCore Documentation</a>...</p>
+            <script>
+              window.location.href = "./documentation/specificationcore/";
+            </script>
+          </body>
+          </html>
+          EOF
+
+      - name: Upload artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "./docs"
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/DOCS/INPROGRESS/Phase4_Tutorials_Planning.md b/DOCS/INPROGRESS/Phase4_Tutorials_Planning.md
@@ -0,0 +1,192 @@
+# Feature Planning: DocC Tutorials for SpecificationCore
+
+## Task Metadata
+- **Created**: 2025-11-20
+- **Completed**: 2025-11-21
+- **Priority**: P2
+- **Estimated Scope**: Large (6-8 hours)
+- **Prerequisites**: Phase 3 complete (all 23 articles created)
+- **Target Layers**: Documentation, Tutorials, Code Samples
+
+## Feature Overview
+
+Create comprehensive DocC tutorials for SpecificationCore that guide developers through learning and using the specification pattern. Tutorials will use the `.tutorial` format with step-by-step code examples, explanations, and visual aids.
+
+## Implementation Plan
+
+### Phase 4.1: Tutorial Structure Setup
+- [x] Create `Sources/SpecificationCore/Documentation.docc/Tutorials/` directory structure
+- [x] Create tutorial table of contents file
+- [x] Plan tutorial progression (beginner → intermediate → advanced)
+- [x] Identify code sample requirements for each tutorial
+
+### Phase 4.2: Tutorial 1 - Getting Started with SpecificationCore
+**Goal**: Introduce developers to basic specification concepts and simple usage
+
+Steps:
+- [x] Section 1: Understanding Specifications
+  - Explain the Specification pattern
+  - Show protocol definition
+  - Create first simple specification
+  - Test the specification
+
+- [x] Section 2: Using Context and Providers
+  - Introduce EvaluationContext
+  - Show DefaultContextProvider usage
+  - Record events and set counters
+  - Evaluate specifications with context
+
+- [x] Section 3: Composing Specifications
+  - Show AND, OR, NOT operators
+  - Build composite specifications
+  - Test composed logic
+
+- [x] Section 4: Built-in Specifications
+  - Use MaxCountSpec for limits
+  - Use TimeSinceEventSpec for delays
+  - Combine built-in specs
+
+**Code Samples Created**:
+- getting-started-01-first-spec.swift
+- getting-started-01-first-spec-02.swift
+- getting-started-01-first-spec-03.swift
+- getting-started-02-with-context.swift
+- getting-started-02-with-context-02.swift
+- getting-started-03-composition.swift
+- getting-started-03-composition-02.swift
+- getting-started-03-composition-03.swift
+- getting-started-04-built-in-specs.swift
+- getting-started-04-built-in-specs-02.swift
+- getting-started-04-built-in-specs-03.swift
+- getting-started-05-testing.swift
+
+### Phase 4.3: Tutorial 2 - Property Wrappers and Declarative Evaluation
+**Goal**: Teach declarative specification usage with property wrappers
+
+Steps:
+- [x] Section 1: @Satisfies Basics
+  - Introduce @Satisfies property wrapper
+  - Show automatic context handling
+  - Use in simple scenarios
+  - Compare to manual evaluation
+
+- [x] Section 2: Decision Specifications
+  - Introduce @Decides for typed results
+  - Create FirstMatchSpec for routing
+  - Use @Maybe for optional results
+  - Handle fallback values
+
+- [x] Section 3: Async Specifications
+  - Introduce @AsyncSatisfies
+  - Create async specifications
+  - Handle async evaluation
+
+- [x] Section 4: Advanced Patterns
+  - Builder patterns for wrappers
+  - Convenience initializers
+  - Projected values
+
+**Code Samples Created**:
+- property-wrappers-01-satisfies-basic.swift
+- property-wrappers-01-satisfies-basic-02.swift
+- property-wrappers-02-decides.swift
+- property-wrappers-02-maybe.swift
+- property-wrappers-03-async.swift
+- property-wrappers-04-advanced.swift
+- property-wrappers-04-advanced-02.swift
+
+### Phase 4.4: Tutorial 3 - Macros and Advanced Composition
+**Goal**: Show macro-assisted specification creation and complex patterns
+
+Steps:
+- [x] Section 1: @specs Macro
+  - Introduce @specs for composition
+  - Create composite specs declaratively
+  - Test macro-generated specs
+
+- [x] Section 2: @AutoContext Macro
+  - Introduce @AutoContext
+  - Enable automatic provider access
+  - Combine @specs and @AutoContext
+
+- [x] Section 3: Complex Specifications
+  - Build multi-condition eligibility specs
+  - Create tiered access control
+  - Implement time-based rules
+  - Chain specifications
+
+- [x] Section 4: Testing and Best Practices
+  - Use MockContextProvider
+  - Test specifications thoroughly
+  - Common patterns and pitfalls
+
+**Code Samples Created**:
+- macros-01-specs-basic.swift
+- macros-01-specs-complex.swift
+- macros-02-auto-context.swift
+- macros-02-combined.swift
+- macros-03-ecommerce.swift
+- macros-03-subscription.swift
+- macros-04-testing.swift
+- macros-04-best-practices.swift
+
+### Phase 4.5: Create Code Sample Files
+- [x] Create all code sample files in correct format
+- [x] Add inline comments and explanations
+- [x] Validate @Code references in tutorials
+
+### Phase 4.6: Create Visual Assets (Optional)
+- [ ] Skipped - text-only tutorials for initial release
+
+### Phase 4.7: Tutorial Validation
+- [x] Build documentation locally
+- [x] Verify all tutorials render correctly
+- [x] Check all code samples are reachable
+- [x] Test tutorial navigation
+
+## Files Created
+
+### Tutorial Files (4 files)
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/Tutorials.tutorial`
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/GettingStartedCore.tutorial`
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/PropertyWrappersGuide.tutorial`
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/MacrosAndAdvanced.tutorial`
+
+### Code Sample Files (27 files)
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/getting-started-*.swift` (12 files)
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/property-wrappers-*.swift` (7 files)
+- `Sources/SpecificationCore/Documentation.docc/Tutorials/Resources/Code/macros-*.swift` (8 files)
+
+## Test Strategy
+
+- [x] Build documentation: `swift package generate-documentation --target SpecificationCore`
+- [x] Verify tutorial rendering
+- [x] Test on clean DocC build
+
+## Success Criteria
+
+- [x] All 3 tutorials created and render correctly
+- [x] All code samples created
+- [x] Tutorial navigation works end-to-end
+- [x] Documentation builds without errors
+- [x] Tutorials provide clear learning path for developers
+- [x] Code samples demonstrate real-world usage
+
+## Open Questions (Resolved)
+
+- Should tutorials include images/diagrams? **Decision: Text-only for initial release**
+- Should we create a 4th tutorial? **Decision: 3 tutorials sufficient for now**
+- What level of detail is appropriate? **Decision: Progressive complexity from beginner to advanced**
+
+## Implementation Notes
+
+### Tutorial Structure
+- Tutorial 1 (25 min): Getting Started - basics, context, composition, built-in specs
+- Tutorial 2 (20 min): Property Wrappers - @Satisfies, @Decides, @Maybe, async
+- Tutorial 3 (25 min): Advanced - macros, complex specs, testing, best practices
+
+### Code Sample Guidelines Applied
+- Samples are focused and concise
+- Progressive enhancement (each step builds on previous)
+- Comments explain key concepts
+- Realistic variable names and scenarios
diff --git a/DOCS/INPROGRESS/Phase5_Cleanup_Validation_Planning.md b/DOCS/INPROGRESS/Phase5_Cleanup_Validation_Planning.md
@@ -0,0 +1,113 @@
+# Feature Planning: Documentation Cleanup and Validation
+
+## Task Metadata
+- **Created**: 2025-11-20
+- **Completed**: 2025-11-21
+- **Priority**: P1
+- **Estimated Scope**: Medium (3-4 hours)
+- **Prerequisites**: Phase 3 complete (all 23 articles created)
+- **Target Layers**: Documentation, CI/CD, Quality Assurance
+
+## Feature Overview
+
+Address all warnings and issues from the DocC build, improve documentation quality, validate cross-references, fix circular dependencies, and ensure documentation builds cleanly.
+
+## Implementation Summary
+
+### Phase 5.1: Fix Ambiguous Symbol References
+- [x] Fixed AnySpecification.md init disambiguation
+- [x] Fixed AsyncSatisfies.md init disambiguation
+- [x] Fixed Decides.md init disambiguation
+- [x] Removed invalid hash-based disambiguations
+
+### Phase 5.2: Resolve Circular Reference Cycles
+- [x] Fixed Protocol → Implementation cycles in all files
+- [x] Removed "Related Types" sections from Topics that caused cycles
+- [x] Files fixed: AnySpecification, AsyncSatisfies, ContextProviding, CooldownIntervalSpec, DateComparisonSpec, DateRangeSpec, AsyncSpecification, MaxCountSpec, TimeSinceEventSpec, FirstMatchSpec, DecisionSpec, Maybe, Satisfies, PredicateSpec, AutoContextMacro, DefaultContextProvider, MockContextProvider, Decides
+
+### Phase 5.3: Clean Up Extraneous Content
+- [x] Removed "(from Specification)" annotations from Topics
+- [x] Removed "(Comparable)" annotations from Topics
+- [x] Fixed SpecificationOperators.md build references
+- [x] Fixed AsyncSpecification.md bridging section
+
+### Phase 5.4: Fix Missing Symbols
+- [x] Changed SpecsMacro.md title to not reference non-existent symbol
+- [x] Changed AutoContextMacro.md title to not reference non-existent symbol
+- [x] Changed SpecificationCore.md macro references to use doc: links
+- [x] Fixed cross-references between macro articles
+
+### Phase 5.5: Validate Documentation Links
+- [x] All doc: references validated
+- [x] Changed symbol links to doc: links where appropriate
+
+### Phase 5.6: Build and Test
+- [x] swift build - Success
+- [x] swift package generate-documentation - Success
+- [x] swiftformat --lint - 0 errors
+
+### Phase 5.7: Quality Improvements
+- [x] Tutorial code samples formatted with SwiftFormat
+
+## Warning Reduction Summary
+
+| Stage | Warning Count |
+|-------|---------------|
+| Starting | 177 |
+| After circular ref fixes | 65 |
+| After symbol fixes | 46 |
+| After more cleanup | 39 |
+| Final (remaining are source comments) | ~39 |
+
+## Remaining Warnings (Not in Article Files)
+
+The remaining ~39 warnings are:
+- 17 "Only links allowed in task group" - in Swift source doc comments
+- 7 "Extraneous content" - in Swift source doc comments  
+- 4 "specs doesn't exist" - macro in separate target
+- 3 "Missing Image child directive" - tutorial images not provided
+- Others: references to macros in separate target
+
+These are in Swift source file documentation comments, not the article .md files, and would require modifying the source code documentation.
+
+## Files Modified
+
+### Article Files (18 files)
+- AnySpecification.md
+- AsyncSatisfies.md
+- AsyncSpecification.md
+- AutoContextMacro.md
+- ContextProviding.md
+- CooldownIntervalSpec.md
+- DateComparisonSpec.md
+- DateRangeSpec.md
+- Decides.md
+- DefaultContextProvider.md
+- FirstMatchSpec.md
+- MaxCountSpec.md
+- MockContextProvider.md
+- PredicateSpec.md
+- Satisfies.md
+- SpecificationCore.md
+- SpecificationOperators.md
+- SpecsMacro.md
+
+### Tutorial Files (1 file)
+- Tutorials/Tutorials.tutorial (removed @Resources section)
+
+### Code Sample Files (14 files formatted)
+- SwiftFormat applied to all code samples in Tutorials/Resources/Code/
+
+## Success Criteria
+
+- [x] Significant reduction in warnings (177 → 39)
+- [x] All circular reference cycles in article files resolved
+- [x] Documentation builds successfully
+- [x] SwiftFormat lint passes with 0 errors
+- [x] swift build passes
+
+## Notes
+
+- Remaining warnings are in Swift source file doc comments, not article files
+- Macro symbols (specs, AutoContext) are in a separate macros target, hence warnings
+- Tutorial images were not created (optional per Phase 4 plan)