docs: improve clarity of example code marking in starter template (#101)

- Added prominent header comments to example files marking them for removal
- Added subtle markers to template infrastructure files
- Updated GETTING_STARTED.md with clear distinction info box
- Added note to README.md about example code

Closes #97

Author: sapientpants

.changeset/improve-example-code-clarity.md

@@ -0,0 +1,13 @@
+---
+'agentic-node-ts-starter': patch
+---
+
+docs: Improve clarity of example code marking in starter template
+
+- Added prominent header comments to all example files (src/index.ts, tests/\*.spec.ts) marking them as "EXAMPLE CODE - REPLACE WITH YOUR IMPLEMENTATION"
+- Added subtle header comments to template infrastructure files marking them as production-ready and customizable
+- Updated GETTING_STARTED.md with an info box clearly distinguishing between example code to remove and template infrastructure to keep
+- Added note to README.md explaining that the template includes marked example code
+- All files now have clear visual indicators helping developers quickly identify what to keep vs. what to replace
+
+This change addresses issue #97 by making it immediately apparent which files are examples versus production-ready template code, reducing confusion for new users adopting the starter template.

README.md

@@ -2,6 +2,8 @@
 
 A **batteries-included** TypeScript starter template with comprehensive testing, code quality automation, and security scanning. Built for modern Node.js development with an agentic coding workflow.
 
+> **Note:** This template includes example code to demonstrate its capabilities. These example files are clearly marked with header comments and should be removed when starting your project. See [Getting Started](./docs/GETTING_STARTED.md#clean-up-example-code) for details.
+
 ## 🛠️ Tech Stack
 
 **Core:** Node.js 22+ • TypeScript 5.9 (strict) • pnpm 10.15  

docs/GETTING_STARTED.md

@@ -85,6 +85,25 @@ Edit `package.json`:
 
 ### 4. Clean Up Example Code
 
+> [!IMPORTANT]
+> **Understanding Template Files**
+>
+> This template includes two types of files:
+>
+> - **📝 Example Code**: Demonstration files that should be removed or replaced:
+>   - `src/index.ts` - Example add function with validation demos
+>   - `tests/index.spec.ts` - Example unit tests
+>   - `tests/add.property.spec.ts` - Example property-based tests
+> - **🏗️ Template Infrastructure**: Production-ready code that you can keep and customize:
+>   - `src/logger.ts` - Structured logging with Pino
+>   - `src/dev/debug-utils.ts` - Development debugging utilities
+>   - `tests/logger.spec.ts` - Logger tests
+>   - `tests/container-scan.spec.ts` - Container security tests
+>   - `tests/documentation.spec.ts` - Documentation validation tests
+>   - All configuration files (TypeScript, ESLint, Prettier, etc.)
+>
+> Look for header comments in files to identify their purpose.
+
 Remove the example files and create your own:
 
 ```bash

src/dev/debug-utils.ts

@@ -1,6 +1,7 @@
 /**
- * Development and debugging utilities
- * Only available in development mode
+ * Development and debugging utilities - Template infrastructure.
+ * This file provides helpful debugging tools and can be kept and customized.
+ * Only available in development mode.
  */
 
 /* eslint-disable no-console, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return */

src/index.ts

@@ -1,3 +1,14 @@
+/**
+ * ============================================================================
+ * EXAMPLE CODE - REPLACE WITH YOUR IMPLEMENTATION
+ * ============================================================================
+ * This file contains example code demonstrating the template's capabilities.
+ * It should be removed or replaced with your actual application code.
+ *
+ * See docs/GETTING_STARTED.md#clean-up-example-code for cleanup instructions.
+ * ============================================================================
+ */
+
 import { createChildLogger } from './logger.js';
 
 const logger = createChildLogger('index');

src/logger.ts

@@ -1,3 +1,8 @@
+/**
+ * Production-ready logger configuration using Pino.
+ * This file is part of the template infrastructure and can be kept and customized.
+ */
+
 import pino, { type Logger as PinoLogger, type LoggerOptions } from 'pino';
 
 /**

tests/add.property.spec.ts

@@ -1,3 +1,14 @@
+/**
+ * ============================================================================
+ * EXAMPLE TEST - REMOVE OR REPLACE THIS FILE
+ * ============================================================================
+ * This test file demonstrates property-based testing patterns for example code.
+ * It should be removed or replaced with tests for your actual application.
+ *
+ * See docs/GETTING_STARTED.md#clean-up-example-code for cleanup instructions.
+ * ============================================================================
+ */
+
 import { describe, it } from 'vitest';
 import fc from 'fast-check';
 import { add } from '../src/index.js';

tests/container-scan.spec.ts

@@ -1,3 +1,8 @@
+/**
+ * Tests for container security scanning - Template infrastructure.
+ * These tests verify container scanning setup and can be kept/customized.
+ */
+
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { execFileSync } from 'child_process';
 import {

tests/documentation.spec.ts

@@ -1,3 +1,8 @@
+/**
+ * Tests for documentation - Template infrastructure.
+ * These tests verify documentation quality and can be kept/customized.
+ */
+
 import { describe, it, expect } from 'vitest';
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';

tests/index.spec.ts

@@ -1,3 +1,14 @@
+/**
+ * ============================================================================
+ * EXAMPLE TEST - REMOVE OR REPLACE THIS FILE
+ * ============================================================================
+ * This test file demonstrates testing patterns for the example code.
+ * It should be removed or replaced with tests for your actual application.
+ *
+ * See docs/GETTING_STARTED.md#clean-up-example-code for cleanup instructions.
+ * ============================================================================
+ */
+
 import { describe, it, expect } from 'vitest';
 import { add } from '../src/index.js';