* chore(instruction): Add content-editing skill documentation workflow
guide
* Phase 1: Add CLI configuration system
- Add config-loader.js with .env support and smart repo detection
- Add config/.env.example template (no real values)
- Add config/README.md with comprehensive configuration docs
- Configuration uses generic flags (DOCS_ENTERPRISE_ACCESS) not private repo names
- All .env files already gitignored via existing .gitignore pattern
Validation:
✅ Config loads and finds docs-v2 repo automatically
✅ Defaults work without .env file (hasEnterpriseAccess=false)
✅ .env files properly gitignored
* Phase 2: Migrate libraries with security fix and quick wins
**Shared Libraries Added:**
- content-utils.js - Shared content detection and management
- api-auditor.js - API documentation auditing (WITH SECURITY FIX)
- api-audit-reporter.js - API audit report generation
- api-parser.js - Parse API definitions from code
- api-request-parser.js - Parse API request/response specs
- api-doc-scanner.js - Scan documentation for API coverage
- telegraf-auditor.js - Telegraf plugin auditing
- telegraf-audit-reporter.js - Telegraf audit reports
- version-utils.js (NEW) - Version normalization utilities
**SECURITY FIX APPLIED:**
❌ Removed: hardcoded 'https://github.com/influxdata/influxdb_pro.git'
❌ Removed: directory name 'influxdb-pro-clone'
✅ Added: Uses process.env.INFLUXDB_PRO_REPO_URL from config
✅ Added: Clear error message if not configured
✅ Added: Generic directory name 'enterprise-clone'
**Quick Wins Added:**
1. Version normalization (version-utils.js)
- Handles v3.9, 3.9, v3.9.0, 3.9.0 automatically
- Suggests matching tags when version not found
2. Enhanced path discovery (config-loader.js)
- Searches parent directories (up to 3 levels)
- Finds sibling repositories automatically
3. Progress indicators (deferred to Phase 3)
- Will add ora package with commands
Validation:
✅ grep shows NO 'influxdb_pro' or 'influxdb-pro' references
✅ api-auditor.js uses process.env.INFLUXDB_PRO_REPO_URL
✅ All library files import successfully
* Phase 3: Add new commands
**Commands Added:**
- audit.js - API and Telegraf documentation auditing
- release-notes.js - Generate release notes from git commits
- add-placeholders.js - Add placeholder syntax to code blocks (moved from scripts/)
**Changes:**
- Created scripts/docs-cli/commands/ directory
- Wrapped add-placeholders.js for CLI router compatibility
- Updated package.json: docs:add-placeholders script path
- Added CLI-MIGRATION-DESIGN.md documentation
**Command Structure:**
All commands export default async function for unified CLI router:
export default async function commandName({ args, command }) { ... }
Validation:
✅ All three command files present in commands/
✅ add-placeholders.js has export wrapper
✅ package.json points to new location
* Phase 4: Update existing commands (create, edit)
**Commands Updated:**
- Moved docs-create.js → commands/create.js
- Moved docs-edit.js → commands/edit.js
**Changes:**
Both commands now:
- Located in commands/ directory for consistency
- Use unified CLI structure (export default async function)
- Maintain findDocsV2Root() for portability
- Can be called via router or directly
**Files Removed:**
- scripts/docs-cli/docs-create.js (moved to commands/)
- scripts/docs-cli/docs-edit.js (moved to commands/)
Validation:
✅ Old files removed
✅ New files in commands/ directory
✅ Git detected as rename (preserves history)
✅ Both have proper export wrappers for CLI router
* Phase 5: Update router with dynamic command loading
**Router Updated:**
- Replaced basic router with enhanced version from docs-tooling
- Dynamic command loading from ./commands/ directory
- Comprehensive help with all commands listed
- Better error handling with DEBUG mode support
- Version flag (--version) support
**Changes:**
- Updated help text for docs-v2 (was docs-tooling)
- Added add-placeholders command to help
- Fixed configuration path references
- Updated GitHub URL to docs-v2
**Features:**
- Handles --help, --version, unknown commands
- Shows usage on error
- DEBUG env var for stack traces
- Clean error messages for missing commands
Validation:
✅ docs --help shows all 5 commands
✅ Help text references correct paths
✅ Router loads commands dynamically
✅ Error handling works correctly
* Fix: Correct package.json path for --version flag
The router was looking in scripts/package.json instead of repo root.
Updated to go up two levels: docs-cli -> scripts -> repo root
Test: npx docs --version now works correctly
* feat: Enhance docs CLI with placeholders alias and update documentation
- Add command alias support to router (placeholders -> add-placeholders)
- Update docs-cli-workflow SKILL.md with all 5 CLI commands
- Update content-editing SKILL.md quick reference with new commands
- Create consolidated influxdb3-tech-writer agent for all v3 products
- Document tech-writer agent consolidation recommendation
* chore(claude): Consolidate tech-writer agents:
1. **influxdb3-tech-writer** (consolidated) - Handles ALL InfluxDB 3
products
- InfluxDB 3 Core (self-hosted, open source)
- InfluxDB 3 Enterprise (self-hosted, licensed)
- InfluxDB 3 Cloud Dedicated (managed, dedicated)
- InfluxDB 3 Cloud Serverless (managed, serverless)
- InfluxDB 3 Clustered (Kubernetes)
2. **influxdb1-tech-writer** (unchanged) - Handles InfluxDB v1 legacy
products
- InfluxDB v1 OSS
- InfluxDB v1 Enterprise
- Chronograf, Kapacitor
* fix: Fix CLI import paths and add npm run scripts
- Fix create.js imports: content-scaffolding, file-operations, url-parser
now correctly reference ../../lib/ (scripts/lib/)
- Fix edit.js import: url-parser now references ../../lib/
- Fix create.js REPO_ROOT: change const to let for reassignment
- Update package.json with all docs:* npm scripts routing through unified CLI
- Improve error handling: distinguish unknown commands from runtime errors
* fix: Fix remaining dynamic import paths in create.js, add integration tests
- Fix dynamic imports in create.js (lines 487, 1286) using wrong paths
- Add cli-integration.test.js that catches import/module errors by
actually executing commands, not just testing --help
- Tests verify commands load and run without ERR_MODULE_NOT_FOUND
- Update run-tests.sh to include integration tests
This would have caught the import path errors that broke 'docs create'.
* fix: Fix argument parsing for CLI router, improve integration tests
- create.js: Pass args from router to parseArgs() instead of re-reading
process.argv (which includes 'create' as first positional)
- add-placeholders.js: Refactor to defer argument parsing to main()
instead of parsing at module load time
- cli-integration.test.js: Stricter tests that check exit codes and
error patterns, not just import errors
- Tests now verify commands actually execute successfully, catching
runtime errors that --help tests would miss
* fix: Fix .tmp directory location and worktree detection
- findDocsV2Root(): Fix package.json name check (@influxdata/docs-site)
- findDocsV2Root(): Prioritize cwd walk-up over env var to find worktrees
- create.js: Change path constants to let for proper reassignment
- .tmp now correctly created in repo root, not scripts/docs-cli/
* chore(docs-cli): Handle piping in create command with helpful errors and
skips
* refactor(docs-cli): unify flag syntax and improve configuration
- Separate --products (product keys) from --repos (paths/URLs) in
release-notes and audit commands
- Use consistent <positional> --flags syntax across commands
- Replace INFLUXDB_PRO with INFLUXDB_ENTERPRISE naming
- Move config from .env to YAML format (~/.influxdata-docs/docs-cli.yml)
- Output release notes to .tmp/release-notes/ (gitignored)
- Add integration tests for new flag syntax
- Update help text to reflect unified CLI usage
* chore: remove deprecated release-notes script and configs
- Remove helper-scripts/common/generate-release-notes.js (migrated to unified CLI)
- Remove orphaned config files (influxdb-v1.json, influxdb-v2.json, etc.)
- Update workflows to reference unified CLI (docs release-notes)
- Update helper-scripts READMEs to remove deprecated documentation
* feat(docs-cli): add path support to --products flag
Add a unified product-resolver module that accepts content paths
(e.g., /influxdb3/core) in addition to product keys (influxdb3_core)
for the --products flag across all docs CLI commands.
Changes:
- Add lib/product-resolver.js for path-to-key resolution
- Update audit command: remove positional args, use --products/--repos
- Update release-notes: add path support, enforce mutual exclusion
- Update create: add path support via resolveProducts()
- Update main CLI help text with new syntax examples
- Add 30 unit tests for product-resolver module
- Update integration tests for new audit syntax
BREAKING CHANGE: audit command no longer accepts positional arguments.
Use `docs audit --products influxdb3_core` instead of `docs audit core`.
* Update skills and commands for new docs CLI syntax
- Update content-editing skill with new --products flag syntax
- Document path-to-key resolution (e.g., /influxdb3/core -> influxdb3_core)
- Update Quick Reference table with correct command examples
- Update docs-cli-workflow skill
- Add examples showing both product keys and content paths
- Document mutual exclusion between --products and --repos
- Update audit command syntax (removed positional arguments)
- Replace enhance-release-notes.md with prepare-release-notes.md
- New command documents docs release-notes CLI usage
- Includes examples with --products and --repos flags
* feat(github): add Copilot instructions management and DRY refactor
- Add copilot-instructions-agent.md for creating/managing Copilot instructions
- DRY refactor of copilot-instructions.md (485→240 lines, 50% reduction)
- Update all pattern-specific instructions to reference Claude skills
- Add comprehensive cross-references between Copilot and Claude resources
- Document unified docs CLI with non-blocking defaults
- Add COPILOT-INSTRUCTIONS-UPDATE.md summary document
Key improvements:
- Single source of truth (Claude skills) with focused Copilot summaries
- Concise, scannable instructions with links to detailed resources
- Consistent structure across all instruction files
- Better guidance on when to use CLI tools vs direct editing
* refactor(docs-cli): fix unused code and env var naming
Address PR feedback from Copilot code review:
- Rename INFLUXDB_ENTERPRISE_REPO_URL to INFLUXDB3_ENTERPRISE_REPO_URL
for consistency with InfluxDB 3 naming conventions
- Fix misleading error message to point to correct config location
- Remove unused detectEnterpriseEndpoints import from api-auditor.js
- Remove unused endpointParams variable from api-auditor.js
- Remove unused auditType variable in audit.js loop
- Remove unused assertDeepEquals function from product-resolver tests
* feat(askai): add Kapa.ai source group filtering for InfluxDB v3
- Add ai_source_group_ids field to all InfluxDB v3 products in data/products.yml
- Add getProductSourceGroupIds() function to retrieve source group IDs from product data
- Enables filtered AI responses using Kapa source groups for documentation pages
- Follows existing pattern for dynamic product configuration
- Implement version-specific config support (__v1, __v2 suffixes)
- Append version hints to example questions for InfluxDB database products only
- Make example questions generic (remove product-specific names)
- Tools (Telegraf, Chronograf, Kapacitor, Flux, Explorer) display questions without version hints
- Pre-fills chat input with [version: /path/] for InfluxDB database products
- Users can easily edit or remove the pre-filled text
- Works for manual opens (Cmd+K) and programmatic opens
- Converts module to TypeScript
* refactor(ask-ai): change version format to 'My version: <product name>'
Use human-readable product names instead of URL paths for better UX.
Example: 'My version: InfluxDB 3 Core' instead of '[version: /influxdb3/core/]'
* fix(ask-ai): restore working Kapa.open() pre-fill implementation
- Replace textarea detection with direct Kapa.open() call
- Add Kapa preinitialization code
- Use click handler on .ask-ai-open button with capture phase
- Handle conversation reset event to re-fill version context
- Remove console logging for cleaner production code
* fix(ask-ai): remove parentheses from example questions for consistency
Make example question format match the pre-fill format:
- Before: 'question (My version: product)'
- After: 'question My version: product'
This ensures users don't think there's a difference between the two formats.
* fix(askai): add Explorer product mapping for Ask AI widget
- Add influxdb3_explorer mapping to getCurrentProductData()
- Add explorer context to getContext() function
- Ensures Explorer pages use correct ai_sample_questions from products.yml
- Reorder Explorer questions with 'install and run' first
This fixes the issue where Explorer Ask AI widget was showing wrong
example questions by properly loading the influxdb3_explorer config.
* test(page-context): add comprehensive e2e tests for product mappings
Add Cypress tests to validate page-context.js correctly identifies:
- Product context values for all InfluxDB products
- Product data from products.yml configuration
- Version information
- AI sample questions and source group IDs
- Placeholder host values
Tests cover:
- InfluxDB 3 (Core, Enterprise, Explorer, Cloud variants, Clustered)
- InfluxDB v2 and v1
- InfluxDB Cloud (TSM)
- Tools (Telegraf, Chronograf, Kapacitor, Flux)
Validates the fix for Explorer Ask AI showing correct example questions.
Related to #jts-askai-group-filters branch work.
* feat(test): add --no-mapping flag to e2e test runner
Allow running functionality tests without requiring content file paths.
The --no-mapping flag skips content-to-URL mapping, making it easier
to run tests that don't depend on specific content files.
Usage:
# With content mapping (for content-specific tests)
node run-e2e-specs.js content/influxdb3/core/_index.md
# Without content mapping (for functionality tests)
node run-e2e-specs.js --spec cypress/e2e/page-context.cy.js --no-mapping
Benefits:
- Simplifies running functionality tests like page-context.cy.js
- Reduces test startup time by skipping unnecessary file mapping
- Makes test commands clearer about their purpose
The page-context test was updated to work correctly with this flag.
* deps: update caniuse and related hook files
* test: Add a `--no-mapping` flag to run tests without specific content files (i.e., test contains all the URLs it needs)
* chore(ask-ai): Format example questions
* test(page-context): add comprehensive e2e tests for all products in products.yml
- Expanded test suite from 6 to 27 tests covering all products
- Added tests for InfluxDB 3 products (Explorer, Core, Enterprise, Cloud Serverless, Cloud Dedicated, Clustered)
- Added tests for InfluxDB v2 and Cloud (TSM)
- Added tests for InfluxDB v1 and Enterprise v1
- Added tests for other products (Telegraf, Chronograf, Kapacitor, Flux)
- Validates page mappings in page-context.js
- Validates AI sample questions configuration in products.yml
- All 27 tests passing
* fix(page-context): correct enterprise_influxdb URL pattern matching
- Changed pattern from /enterprise_v1/ to /enterprise_influxdb/
- Fixes Ask AI example questions not showing correctly for Enterprise v1
- Pattern now matches actual URL structure /enterprise_influxdb/v1/
- All 27 e2e tests passing
* test(page-context): add UI validation for Ask AI widget configuration
- Added 4 tests checking Kapa widget script data attributes
- Tests verify data-modal-example-questions contains correct product-specific questions
- Validates Explorer, Core, Enterprise, and Enterprise v1 configurations
- All 31 tests passing (27 existing + 4 new UI tests)
* feat(ask-ai): add help in Ask AI widget placeholder
- InfluxDB placeholder recommends specifying product and version
- Fix page-context.js to use products.influxdb_cloud instead of products.cloud
- Add UI tests verifying version-specific naming in Kapa widget script tags
* feat(ask-ai): Tailors placeholder for each version/product. Disables "Viewing <product>" in disclaimer note.
Jason Stirnaman