AI CHAT TASK UPDATING TIMESTAMPS Always be sure to update relevant timestamps in a doc after editing the doc.

MANDATORY BUILD COMMAND FOR AI RESPONSES

Whenever the user asks how to build, preview, or test the site, always provide this command first and foremost:

echo "1" | npm run menu

This is the ONLY correct answer for "how do I build/preview/test?"
Do NOT suggest
```
npm run build
```
,
```
npm start
```
, or any other command unless the user specifically asks for an alternative.
Always show this command in a code block, as above, at the start of your answer.
This guarantees the correct workflow, menu selection, and "continue" button in VS Code.
Important: If providing this command in a response, ensure it is the last thing shown to the user.
Important: Do not provide multiple commands unless explicitly requested by the user.

Rather than open ended prompts such as "Let me know if this fully resolves the issue or if you need further tweaks!", provide specific follow-up questions or actions.

AI Chat Task Continuation Policy

AI Chat: When prompting the user to preview or test, always use the following command to ensure the menu item is pre-selected and the interactive "continue" button is shown in the terminal:

echo "1" | npm run menu

This is the default and preferred workflow for all AI-driven development and testing. It guarantees:

The menu runs with option 1 pre-selected (local development)
The "continue" button is always provided in the VS Code terminal for the next step
After completing a task, always review the conversation for any recently discussed but incomplete tasks.
If there are pending tasks, immediately return to them and provide the next command, step, or context needed to continue.
Never end your turn without either fully completing all tasks or clearly providing the next actionable step for the user. - After completing a task (and only when you believe the task is fully complete), always ask the user to confirm if the task is complete, and provide actionable next-step options such as: - 1. Yes, update docs, ready to commit - 2. No, keep trying - 3. No, review and consider more options - 4. Return to previous work (list recent tasks that would make sense to return to)
- **5. Update documentation and commit changes ** AI Chat: If user chooses "5", search for relevant documentation to update, then proceed. - (Options can be dynamic and context-aware as appropriate) - If there are options, always provide them as explicit numbered choices for the user to pick. - At the end of the options, add: - Choose an option like "1" or "2" or say "c" to continue with something else. - If the user picks "c" continue with the next logical step in the conversation.

applyTo: '**'

Development Workflow & VS Code Instructions

Current workflows and development guidelines for the repo.

🚀 Quick Start Commands

Coding standards, domain knowledge, and preferences that AI should follow.

Please start every response with an emoji

Prompt Style Guidelines

Emoji System for AI Responses

Use these at the start of each AI response for clarity:

✅ = complete/success
⚠️ = issue/warning
💬 = options/clarification
🚧 = in progress
🔍 = searching/auditing
📝 = doc/note
🟢 = ready/green-light

Response Style

Use plain, simple language
Be concise (e.g., say “Agreed.” instead of “You're absolutely right…”)
Skip blame or filler — just provide the fix
Ask for clarification if the request is ambiguous
Use consistent terminology and formatting
Prefer bulleted lists for clarity
Provide examples or analogies when useful
Explain reasoning briefly when needed

Solution Guidelines

Favor reliable, well-known methods
Offer step-by-step instructions when applicable
Suggest tools or approaches I may not have considered
Avoid over-engineering or unnecessary files
Prioritize maintainability and clarity
Follow existing patterns and conventions where possible
Document decisions and rationale clearly
Simplify especially if something has failed multiple times

Context

Environment: macOS in VS Code
Project Focus: Personal portfolio static site (HTML, CSS, vanilla JS/ESM)
Workflow: Custom Node.js build system, npm scripts, shell commands, Git for build-time change detection
Style: Structured, maintainable code; deep build pipeline knowledge
Role: Senior Product Designer with strong front-end skills

Tone + Depth

Technical Level: Mid-to-senior front-end/build tools; skip beginner explanations
Clarity: Focus on how/why solutions work in this setup
Code: Examples relevant to structure/conventions (e.g.,
```
dev/scripts/...
```
, 2-space Prettier)

Experimental Suggestions

Creativity: Open to clever/unconventional ideas, especially for automation/workflow
Constraints: Stick to Node.js, shell scripts, vanilla JS
Risk Framing: Pitch experiments as low-risk, easy to test; include benefits/trade-offs

Build System Quick Commands

Build site and start preview:
```
npm run build
```
Main build pipeline + preview server (most common workflow)
Start preview server only:
```
npm start
```
Local server to preview existing build
Interactive menu:
```
npm run menu
```
Interactive menu with Build & Preview, Start Server, Deploy, etc.
Preview a specific page:
```
PAGE=/portfolio/tags/ npm run preview:page
```
Build/preview just one page (replace path as needed)
Watch for changes (auto-rebuild):
```
npm run dev
```
Dev server with file watching
Lint all JS files:
```
npm run lint
```
Run ESLint on the codebase
Format codebase:
```
npm run format
```
Apply Prettier to all source files
Run a specific build script:
```
node build-system/scripts/06-build-portfolio.mjs
```
(Or any script in your scripts/ folder)
Check for build errors:
```
cat build_output.log | tail -20
```
See last 20 lines of the build log
Apply password protection:
```
npm run password:protect
```
Add password protection to pages marked with BUILD_INSERT id="password"
Interactive password protection:
```
npm run menu
```
→ Utilities → Add Password Protection User-friendly interface for adding global password protection to portfolio pages
Smart audit with security tracking:
```
node dev/scripts/deploy/deploy-support/utils/audit.mjs
```
Intelligent audit with "Secure" metric and protected pages list
Sync from private repo:
```
sh scripts/sync-from-private.sh
```
Sync content/config from private sources

Validate HTML output:

node build-system/scripts/00-validate-html.mjs

Run output validation

Semantic Search & Troubleshooting Tips

Confirm you’re in the correct working directory before running scripts (e.g.,
```
danrtzaq/
```
vs.
```
portfolio-build/
```
).
Prefer absolute or project-root-relative paths in scripts and commands.
If a script fails, check for:
- Typos in script names or paths
- Missing dependencies (
```
npm install
```
  )
- File permissions (e.g.,
```
chmod +x script.sh
```
  for shell scripts)
- Required environment variables (e.g.,
```
PAGE=...
```
  )
Use
```
ls
```
or
```
tree
```
to confirm file locations before running custom scripts.
For ambiguous commands, refer to
```
package.json
```
scripts and
```
README.md
```
for canonical usage.
If a command is not found, try
```
npm run <script>
```
or
```
node <path>
```
explicitly.
When in doubt, search for the script/function name in the workspace to find its definition and usage.
Use
```
cat build_output.log | tail -20
```
to quickly diagnose build failures.
For new scripts, add a comment at the top describing usage and required context.

Important Safety Note

Avoid running build scripts that overwrite or modify files in your source directories (e.g.,
```
_source-content/
```
,
```
dev/
```
, or
```
build-system/
```
).
Always confirm the output path and script intent before running new or experimental build scripts.
Prefer running builds that output to a dedicated
```
build/
```
,
```
public_html/
```
, or similar directory.
If unsure, review the script or run it on a test branch to prevent accidental data loss.
Do not search or operate in the
```
postsforpause.com/
```
directory. This folder is not part of the main portfolio build and should be excluded from all automation, search, and build steps.

Workspace & Repo Structure

danrtzaq/ (Private main repo)
- Your primary, private workspace for all source, content, and build scripts
- Contains: custom build system, content, automation, and experimental scripts
portfolio-build/ (Public portfolio-build repo)
- Public-facing, minimal repo for the static portfolio site
- Contains: only the files needed to build and deploy the public site
build-system-repo/
- (If present) Used for modularizing or versioning the build system separately
- Useful for sharing build logic across projects or as a submodule

Git & Workflow Tips

Keep private and public repos clearly separated to avoid accidental leaks
Use
```
.gitignore
```
in both repos to prevent build artifacts, logs, and secrets from being committed
For cross-repo sync, use scripts (e.g.,
```
sync-from-private.sh
```
) and always review diffs before pushing
Use branches for experimental features or major changes; merge to main only after validation
Tag releases in the public repo for clear versioning
Use
```
git status
```
and
```
git diff
```
before every commit to catch accidental changes
For submodules (if using
```
build-system-repo
```
as a submodule), remember to update and commit submodule refs

For more details, see:

```
README.md
```
(project overview, setup, usage)
```
CHANGELOG.md
```
(recent changes/updates)
```
DOCS/DEVELOPER-NOTES.md
```
(technical implementation, build pipeline, and workflows)

GitHub Copilot Instructions

AI FILE SYSTEM LIMITATION POLICY

If an action requires deleting, moving, or renaming files, and the AI does not have the ability to perform it directly, the AI must clearly state this limitation.
In such cases, the AI should provide the exact shell command for the user to run manually.
The AI must never claim to have deleted, moved, or renamed files if it cannot actually do so.

To ensure consistent and high-quality code suggestions from GitHub Copilot, please follow these guidelines when accepting or reviewing AI-generated code:

Changelog Archiving Automation (WIP)

Keep only the 10 most recent releases in
```
DOCS/CHANGELOG.md
```
.
Move older releases to
```
DOCS/CHANGELOG-archive.md
```
.
Ensure archive and main changelog have no duplicate or missing entries.
Add or update the archive link at the top of the main changelog as needed.
(Planned) Automate this process with a Node.js script and a git pre-push hook:
- Script parses
```
CHANGELOG.md
```
  , moves oldest releases to archive if >10 exist.
- Hook runs script before every push.
- Manual review is recommended after automation runs.

See

dev/scripts/archive-changelog.mjs

(to be created) for implementation details.

Always review AI-generated code for correctness, security, and compliance with project standards.
Test any new code or configuration changes in a safe environment before deploying to production.
Be cautious with accepting large code changes or unfamiliar patterns; break them down and review incrementally.
Use version control (e.g., Git) to track changes and facilitate rollback if needed.
Document any AI-generated code or configuration changes thoroughly, including purpose, author, and date.
Regularly update and maintain dependencies, libraries, and tools used in the project to minimize vulnerabilities.
Provide feedback on AI-generated code quality and relevance to improve future suggestions.

Specific Patterns and Practices

For JavaScript/TypeScript code, prefer:
- ```
const
```
  and
```
let
```
  over
```
var
```
  for variable declarations
- Arrow functions for anonymous functions
- Template literals for string concatenation
- Destructuring assignment for objects and arrays
- Default parameters and rest/spread operators for functions
- Async/await for asynchronous code
- Modular, reusable functions with clear input/output contracts
For HTML:
- Use semantic elements (
```
header
```
  ,
```
footer
```
  ,
```
article
```
  ,
```
section
```
  , etc.) appropriately
- Ensure all elements have corresponding closing tags
- Use lowercase for element and attribute names
- Quote attribute values consistently
- Use
```
class
```
  and
```
id
```
  attributes for styling and scripting hooks
- Ensure proper nesting and hierarchy of elements
For CSS:
- Use classes for styling hooks, avoid IDs for styling
- Prefer
```
rem
```
  or
```
em
```
  units for font sizes,
```
px
```
  for borders,
```
vh
```
  /
```
vw
```
  for layout
- Use
```
flexbox
```
  or
```
grid
```
  for layout, avoid floats
- Use
```
@media
```
  queries for responsive design
- Organize styles logically, consider using BEM or similar methodology
- Avoid inline styles, prefer external or internal stylesheets
For Node.js:
- Use
```
const
```
  and
```
let
```
  for variable declarations
- Prefer arrow functions and template literals
- Use async/await for asynchronous code
- Organize code into modules with clear exports/imports
- Handle errors gracefully, use
```
try/catch
```
  with async/await
- Validate and sanitize all input data
- Use environment variables for configuration and secrets
Carousel captions now use a single
with and containing manual bullets, matching the .content-caption pattern for spacing and style. See DESIGN-SYSTEM.md for details.

AI CHAT TASK UPDATING TIMESTAMPS Always be sure to update relevant timestamps in a doc after editing the doc.

MANDATORY BUILD COMMAND FOR AI RESPONSES

Whenever the user asks how to build, preview, or test the site, always provide this command first and foremost:

echo "1" | npm run menu

This is the ONLY correct answer for "how do I build/preview/test?"
Do NOT suggest
```
npm run build
```
,
```
npm start
```
, or any other command unless the user specifically asks for an alternative.
Always show this command in a code block, as above, at the start of your answer.
This guarantees the correct workflow, menu selection, and "continue" button in VS Code.
Important: If providing this command in a response, ensure it is the last thing shown to the user.
Important: Do not provide multiple commands unless explicitly requested by the user.

Rather than open ended prompts such as "Let me know if this fully resolves the issue or if you need further tweaks!", provide specific follow-up questions or actions.

AI Chat Task Continuation Policy

AI Chat: When prompting the user to preview or test, always use the following command to ensure the menu item is pre-selected and the interactive "continue" button is shown in the terminal:

echo "1" | npm run menu

This is the default and preferred workflow for all AI-driven development and testing. It guarantees:

The menu runs with option 1 pre-selected (local development)
The "continue" button is always provided in the VS Code terminal for the next step
After completing a task, always review the conversation for any recently discussed but incomplete tasks.
If there are pending tasks, immediately return to them and provide the next command, step, or context needed to continue.
Never end your turn without either fully completing all tasks or clearly providing the next actionable step for the user. - After completing a task (and only when you believe the task is fully complete), always ask the user to confirm if the task is complete, and provide actionable next-step options such as: - 1. Yes, update docs, ready to commit - 2. No, keep trying - 3. No, review and consider more options - 4. Return to previous work (list recent tasks that would make sense to return to)
- **5. Update documentation and commit changes ** AI Chat: If user chooses "5", search for relevant documentation to update, then proceed. - (Options can be dynamic and context-aware as appropriate) - If there are options, always provide them as explicit numbered choices for the user to pick. - At the end of the options, add: - Choose an option like "1" or "2" or say "c" to continue with something else. - If the user picks "c" continue with the next logical step in the conversation.

applyTo: '**'

Development Workflow & VS Code Instructions

Current workflows and development guidelines for the repo.

🚀 Quick Start Commands

Coding standards, domain knowledge, and preferences that AI should follow.

Please start every response with an emoji

Prompt Style Guidelines

Emoji System for AI Responses

Use these at the start of each AI response for clarity:

✅ = complete/success
⚠️ = issue/warning
💬 = options/clarification
🚧 = in progress
🔍 = searching/auditing
📝 = doc/note
🟢 = ready/green-light

Response Style

Use plain, simple language
Be concise (e.g., say “Agreed.” instead of “You're absolutely right…”)
Skip blame or filler — just provide the fix
Ask for clarification if the request is ambiguous
Use consistent terminology and formatting
Prefer bulleted lists for clarity
Provide examples or analogies when useful
Explain reasoning briefly when needed

Solution Guidelines

Favor reliable, well-known methods
Offer step-by-step instructions when applicable
Suggest tools or approaches I may not have considered
Avoid over-engineering or unnecessary files
Prioritize maintainability and clarity
Follow existing patterns and conventions where possible
Document decisions and rationale clearly
Simplify especially if something has failed multiple times

Context

Environment: macOS in VS Code
Project Focus: Personal portfolio static site (HTML, CSS, vanilla JS/ESM)
Workflow: Custom Node.js build system, npm scripts, shell commands, Git for build-time change detection
Style: Structured, maintainable code; deep build pipeline knowledge
Role: Senior Product Designer with strong front-end skills

Tone + Depth

Technical Level: Mid-to-senior front-end/build tools; skip beginner explanations
Clarity: Focus on how/why solutions work in this setup
Code: Examples relevant to structure/conventions (e.g.,
```
dev/scripts/...
```
, 2-space Prettier)

Experimental Suggestions

Creativity: Open to clever/unconventional ideas, especially for automation/workflow
Constraints: Stick to Node.js, shell scripts, vanilla JS
Risk Framing: Pitch experiments as low-risk, easy to test; include benefits/trade-offs

Build System Quick Commands

Build site and start preview:
```
npm run build
```
Main build pipeline + preview server (most common workflow)
Start preview server only:
```
npm start
```
Local server to preview existing build
Interactive menu:
```
npm run menu
```
Interactive menu with Build & Preview, Start Server, Deploy, etc.
Preview a specific page:
```
PAGE=/portfolio/tags/ npm run preview:page
```
Build/preview just one page (replace path as needed)
Watch for changes (auto-rebuild):
```
npm run dev
```
Dev server with file watching
Lint all JS files:
```
npm run lint
```
Run ESLint on the codebase
Format codebase:
```
npm run format
```
Apply Prettier to all source files
Run a specific build script:
```
node build-system/scripts/06-build-portfolio.mjs
```
(Or any script in your scripts/ folder)
Check for build errors:
```
cat build_output.log | tail -20
```
See last 20 lines of the build log
Apply password protection:
```
npm run password:protect
```
Add password protection to pages marked with BUILD_INSERT id="password"
Interactive password protection:
```
npm run menu
```
→ Utilities → Add Password Protection User-friendly interface for adding global password protection to portfolio pages
Smart audit with security tracking:
```
node dev/scripts/deploy/deploy-support/utils/audit.mjs
```
Intelligent audit with "Secure" metric and protected pages list
Sync from private repo:
```
sh scripts/sync-from-private.sh
```
Sync content/config from private sources

Validate HTML output:

node build-system/scripts/00-validate-html.mjs

Run output validation

Semantic Search & Troubleshooting Tips

Confirm you’re in the correct working directory before running scripts (e.g.,
```
danrtzaq/
```
vs.
```
portfolio-build/
```
).
Prefer absolute or project-root-relative paths in scripts and commands.
If a script fails, check for:
- Typos in script names or paths
- Missing dependencies (
```
npm install
```
  )
- File permissions (e.g.,
```
chmod +x script.sh
```
  for shell scripts)
- Required environment variables (e.g.,
```
PAGE=...
```
  )
Use
```
ls
```
or
```
tree
```
to confirm file locations before running custom scripts.
For ambiguous commands, refer to
```
package.json
```
scripts and
```
README.md
```
for canonical usage.
If a command is not found, try
```
npm run <script>
```
or
```
node <path>
```
explicitly.
When in doubt, search for the script/function name in the workspace to find its definition and usage.
Use
```
cat build_output.log | tail -20
```
to quickly diagnose build failures.
For new scripts, add a comment at the top describing usage and required context.

Important Safety Note

Avoid running build scripts that overwrite or modify files in your source directories (e.g.,
```
_source-content/
```
,
```
dev/
```
, or
```
build-system/
```
).
Always confirm the output path and script intent before running new or experimental build scripts.
Prefer running builds that output to a dedicated
```
build/
```
,
```
public_html/
```
, or similar directory.
If unsure, review the script or run it on a test branch to prevent accidental data loss.
Do not search or operate in the
```
postsforpause.com/
```
directory. This folder is not part of the main portfolio build and should be excluded from all automation, search, and build steps.

Workspace & Repo Structure

danrtzaq/ (Private main repo)
- Your primary, private workspace for all source, content, and build scripts
- Contains: custom build system, content, automation, and experimental scripts
portfolio-build/ (Public portfolio-build repo)
- Public-facing, minimal repo for the static portfolio site
- Contains: only the files needed to build and deploy the public site
build-system-repo/
- (If present) Used for modularizing or versioning the build system separately
- Useful for sharing build logic across projects or as a submodule

Git & Workflow Tips

Keep private and public repos clearly separated to avoid accidental leaks
Use
```
.gitignore
```
in both repos to prevent build artifacts, logs, and secrets from being committed
For cross-repo sync, use scripts (e.g.,
```
sync-from-private.sh
```
) and always review diffs before pushing
Use branches for experimental features or major changes; merge to main only after validation
Tag releases in the public repo for clear versioning
Use
```
git status
```
and
```
git diff
```
before every commit to catch accidental changes
For submodules (if using
```
build-system-repo
```
as a submodule), remember to update and commit submodule refs

For more details, see:

```
README.md
```
(project overview, setup, usage)
```
CHANGELOG.md
```
(recent changes/updates)
```
DOCS/DEVELOPER-NOTES.md
```
(technical implementation, build pipeline, and workflows)

GitHub Copilot Instructions

AI FILE SYSTEM LIMITATION POLICY

If an action requires deleting, moving, or renaming files, and the AI does not have the ability to perform it directly, the AI must clearly state this limitation.
In such cases, the AI should provide the exact shell command for the user to run manually.
The AI must never claim to have deleted, moved, or renamed files if it cannot actually do so.

To ensure consistent and high-quality code suggestions from GitHub Copilot, please follow these guidelines when accepting or reviewing AI-generated code:

Changelog Archiving Automation (WIP)

Keep only the 10 most recent releases in
```
DOCS/CHANGELOG.md
```
.
Move older releases to
```
DOCS/CHANGELOG-archive.md
```
.
Ensure archive and main changelog have no duplicate or missing entries.
Add or update the archive link at the top of the main changelog as needed.
(Planned) Automate this process with a Node.js script and a git pre-push hook:
- Script parses
```
CHANGELOG.md
```
  , moves oldest releases to archive if >10 exist.
- Hook runs script before every push.
- Manual review is recommended after automation runs.

See

dev/scripts/archive-changelog.mjs

(to be created) for implementation details.

Always review AI-generated code for correctness, security, and compliance with project standards.
Test any new code or configuration changes in a safe environment before deploying to production.
Be cautious with accepting large code changes or unfamiliar patterns; break them down and review incrementally.
Use version control (e.g., Git) to track changes and facilitate rollback if needed.
Document any AI-generated code or configuration changes thoroughly, including purpose, author, and date.
Regularly update and maintain dependencies, libraries, and tools used in the project to minimize vulnerabilities.
Provide feedback on AI-generated code quality and relevance to improve future suggestions.

Specific Patterns and Practices

For JavaScript/TypeScript code, prefer:
- ```
const
```
  and
```
let
```
  over
```
var
```
  for variable declarations
- Arrow functions for anonymous functions
- Template literals for string concatenation
- Destructuring assignment for objects and arrays
- Default parameters and rest/spread operators for functions
- Async/await for asynchronous code
- Modular, reusable functions with clear input/output contracts
For HTML:
- Use semantic elements (
```
header
```
  ,
```
footer
```
  ,
```
article
```
  ,
```
section
```
  , etc.) appropriately
- Ensure all elements have corresponding closing tags
- Use lowercase for element and attribute names
- Quote attribute values consistently
- Use
```
class
```
  and
```
id
```
  attributes for styling and scripting hooks
- Ensure proper nesting and hierarchy of elements
For CSS:
- Use classes for styling hooks, avoid IDs for styling
- Prefer
```
rem
```
  or
```
em
```
  units for font sizes,
```
px
```
  for borders,
```
vh
```
  /
```
vw
```
  for layout
- Use
```
flexbox
```
  or
```
grid
```
  for layout, avoid floats
- Use
```
@media
```
  queries for responsive design
- Organize styles logically, consider using BEM or similar methodology
- Avoid inline styles, prefer external or internal stylesheets
For Node.js:
- Use
```
const
```
  and
```
let
```
  for variable declarations
- Prefer arrow functions and template literals
- Use async/await for asynchronous code
- Organize code into modules with clear exports/imports
- Handle errors gracefully, use
```
try/catch
```
  with async/await
- Validate and sanitize all input data
- Use environment variables for configuration and secrets
Carousel captions now use a single
with and containing manual bullets, matching the .content-caption pattern for spacing and style. See DESIGN-SYSTEM.md for details.

**AI Chat Task Continuation Policy**

Related Skills

Nano Banana Pro

Markdown Converter

1password

AI Chat Task Continuation Policy