* 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
* REAL-WORLD TESTING ────────────────── BEFORE FIX: ─────────── ❌ Agent
runs: docs edit <url> ❌ Editor spawns and blocks ❌ Agent hangs for 30+
seconds ❌ Workflow times out or fails ❌ Manual intervention required
AFTER FIX: ────────── ✅ Agent runs: docs edit <url> ✅ Editor spawns
detached ✅ CLI exits in <1 second ✅ Agent continues processing ✅
Workflow completes successfully ✅ No manual intervention needed
ISSUE #21: ✅ RESOLVED ───────────────────────
The docs edit command now: • Works perfectly in automated workflows •
Doesn't hang AI agents or scripts • Exits immediately by default •
Supports blocking mode via --wait flag • Handles both URL formats •
Provides clear feedback • Has comprehensive documentation
DEPLOYMENT STATUS: ✅ READY ────────────────────────────
All tests pass: ✓ Unit tests (7/7) ✓ CLI tests ✓ Real-world agent
workflow ✓ Coverage Gap issue processing ✓ URL format support ✓
Non-blocking verification ✓ Blocking mode verification
Scenario: AI agent processes GitHub Coverage Gap issues Issues: #6702,
Results: • Fetched issues from GitHub ✅ • Used docs edit to locate files
✅ • Identified missing docs (Coverage Gaps) ✅ • Found existing docs ✅ •
No hangs, no timeouts ✅ • Total time: 2 seconds for 3 issues ✅
* refactor(cli): move docs CLI to dedicated scripts/docs-cli directory
- Organize all CLI tools and tests in scripts/docs-cli/
- Update package.json bin and script paths
- Update setup-local-bin.js to point to new location
- Fix import paths in docs-edit.js and docs-create.js
- Update SKILL.md with new features (--wait, --editor, path support)
- Update ISSUE-21-FIX-README.md with new structure
- Add comprehensive README.md for docs-cli directory
- All tests passing, non-blocking behavior verified
Closes#21
* feat(cli): add non-blocking editor support to docs create
- Add --open flag to open created files in editor
- Add --wait flag for blocking mode (use with --open)
- Add --editor flag for explicit editor selection
- Uses same editor resolution and process management as docs edit
- Non-blocking by default to prevent agent hanging
- Update all documentation with new examples
- Maintains backwards compatibility (--open is optional)
This completes the non-blocking implementation across both
docs edit and docs create commands.
* docs: update Copilot instructions with complete CLI tool reference
- Add docs create --open to Quick Reference table
- Document both create and edit commands comprehensively
- Add editor configuration section (shared between commands)
- Update content.instructions.md with CLI workflow examples
- Add NON-BLOCKING-IMPLEMENTATION-COMPLETE.md summary document
- Clarify non-blocking behavior for AI agents
* chore: remove ephemeral documentation files
Remove temporary documentation files used during development:
- CLAUDE-docs-tooling-issue21.md
- IMPLEMENTATION-SUMMARY.md
- ISSUE-21-FIX-README.md
- NON-BLOCKING-IMPLEMENTATION-COMPLETE.md
- TEST-RESULTS.md
All relevant documentation has been integrated into:
- README.md
- scripts/docs-cli/README.md
- .github/copilot-instructions.md
- .github/instructions/content.instructions.md
- .claude/skills/docs-cli-workflow/SKILL.md
* Fix url-parser.js broken import by moving to shared library location (#6727)
* Initial plan
* refactor: move url-parser.js to shared library location and fix imports
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* Update scripts/docs-cli/__tests__/process-manager.test.js
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Update scripts/docs-cli/__tests__/editor-resolver.test.js
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* 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.
Remove contributing.instructions.md build logic and simplify to only
build platform reference from products.yml. Update lefthook to only
trigger on products.yml changes instead of CONTRIBUTING.md.
- Add ODBC driver installation and configuration docs
- Add Power BI Desktop custom connector setup docs
- Configure host, port, and token conditionals for all InfluxDB 3 products
- Set frontmatter with proper metadata and related content
The shared content files (content/shared/influxdb3-query-guides/execute-queries/odbc.md
and content/shared/influxdb3-visualize/powerbi.md) contain product-specific conditionals
for server URLs, ports, and tokens. Each product version sources these shared files.
Next steps: Edit the content/shared files to update any remaining product-specific
instructions in the step-by-step procedures if needed. Server, port, and token
conditionals are already configured throughout the documentation.
- Follow Copilot guidelines for naming instructions files according to the directory they apply to
- Copy instructions files as CLAUDE.md to the relevant directory.
- Update placeholder instructions
- Optimize Copilot instructions
- Remove Claude instructions and reference the Copilot instructions file instead
TODO: update the commit hook script to correctly generate and place the files.
- Add GitHub Actions for automated link validation on PRs
- Implement incremental validation with caching (30-day TTL, configurable)
- Add matrix generator for parallel validation strategy
- Create comprehensive TESTING.md documentation
- Add cache manager with configurable TTL via env var or CLI
- Implement smart link extraction and validation
- Add PR comment generator for broken link reports
- Update Cypress tests to use incremental validation
- Consolidate testing docs from CONTRIBUTING.md to TESTING.md
Key improvements:
- Cache-aware validation only checks changed content
- Parallel execution for large changesets
- Detailed PR comments with broken link reports
- Support for LINK_CACHE_TTL_DAYS env var
- Local testing with yarn test:links
- Reduced false positives through intelligent caching
chore: Modify AI instructions build script to optimize and reduce instructions size. Add test examples for later
chore: Modify AI instructions build script to optimize and reduce instructions size. Add test examples for later
fix(qol): Agent-agnostic contributing instructions
chore(test): Untrack influxdb3 data and plugins used in Docker configurations and testing
chore(test): Untrack influxdb3 data and plugins used in Docker configurations and testing
chore: Modify AI instructions build script to optimize and reduce instructions size. Add test examples for later
- Add CLI ref for influxdb3 update table and ret. period option in Ent- Change volume source to /test for core and ent3 in compose.yaml
- Add alt_links instructions in CONTRIBUTING.md
- Add a script and pre-commit command to generate a CoPilot instructions file from CONTRIBUTING.md guidelines.
- Add custom instructions for CoPilot to help with influxdb3 placeholders
Jason Stirnaman
Jason Stirnaman