* 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
* test(influxdb3): Improve InfluxDB 3 Core and Enterprise Docker services
Improve Docker Compose services and initialization script for testing InfluxDB 3 Core and Enterprise endpoints.
compose.yaml changes:
- Add influxdb3-core service with per-worktree data isolation
- Add influxdb3-core-noauth service for endpoint testing without auth
- Add influxdb3-enterprise service with trial license configuration
- Fix env_file handling (use optional path, remove variable override)
- Add detailed usage comments for each service
New files:
- test/scripts/init-influxdb3.sh: Helper script to initialize services,
create directories, and validate configuration
- Enterprise configuration uses shared data at ~/influxdata-docs/.influxdb3/
to persist license and data across worktrees.
- .claude/skills/influxdb3-test-setup/SKILL.md. It covers:
1. Architecture overview - Shows the directory structure for shared vs per-worktree data
2. Quick reference - Common commands table
3. Setup workflows - Core only, Enterprise only, or both
4. Worktree-specific databases - How to create isolated databases named after the worktree
5. Test environment configuration - Setting up .env.test files for code block tests
6. Troubleshooting - Common issues (license, auth, ports)
7. Service comparison - Core vs Enterprise differences
The skill references the init script but keeps database creation as a separate workflow step, allowing flexibility for different testing scenarios.
* docs(copilot): Document influxdb3-test-setup skill in Copilot instructions (#6751)
* Initial plan
* docs(copilot): Add influxdb3-test-setup skill documentation to instructions
- Add InfluxDB 3 Test Setup subsection under Testing section with quick reference commands
- Add Skills section under Specialized Instructions with all available skills
- Document influxdb3-test-setup skill alongside existing skills (cypress-e2e-testing, docs-cli-workflow, hugo-template-dev)
- Include links to skill files and brief descriptions for discoverability
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>
* chore(ci): Refactor InfluxDB 3 token handling to use JSON secrets
- Store Core and Enterprise tokens as JSON files with metadata
- Update SKILL.md instructions for jq-based token extraction
- Use Docker secrets for secure token mounting in compose.yaml
- Update init-influxdb3.sh to generate JSON token files
- Refactor compose.yaml to mount token files as secrets, not binds
- Standardize API examples and environment setup for new token format
* docs(influxdb3): Update token documentation for Docker Compose and CI/CD (#6756)
- Add 'description' field to offline admin token schema alongside 'expiry_millis'
- Add new section for Docker Compose with preconfigured admin tokens
- Document Docker secrets for secure token management
- Add CI/CD setup instructions using environment variables
- Standardize on INFLUXDB3_AUTH_TOKEN environment variable
Both 'description' and 'expiry_millis' are optional fields supported
by the InfluxDB 3 server when reading preconfigured token files.
* Revert "docs(influxdb3): Update token documentation for Docker Compose and CI…" (#6757)
This reverts commit 5c786ac2fd.
---------
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
* 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>
- 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.
that provides Claude with detailed instructions
for enhancing release notes.
The command includes specific transformation
patterns for different components (database, CLI,
API, etc.) and provides fallback templates for
handling edge cases. It also includes error
handling for common issues like rate limits and
private repositories.
The CLAUDE.md file successfully references 5 key files, all of which exist and are accessible:
1. @README → README.md - Project overview and setup
2. @package.json → package.json - NPM scripts and dependencies
3. @.github/copilot-instructions.md → Main style guidelines and product info
4. @.github/instructions/contributing.instructions.md → Detailed contributing guide
5. @.github/instructions/influxdb3-code-placeholders.instructions.md → InfluxDB 3 specific
guidelines
📊 Current Structure Analysis
The CLAUDE.md file acts as a minimal index that:
- Delegates detailed instructions to other files
- Uses Claude's @ symbol notation for file references
- Provides a clear hierarchy of information
💡 Key Instructions Coverage
Through the linked files, Claude has access to:
- Product documentation paths for all InfluxDB versions
- Style guidelines following Google Developer Documentation standards
- Shortcode usage with extensive examples
- Testing procedures including pytest-codeblocks
- Development workflows with Docker and Node.js
- Placeholder conventions for code examples
- Frontmatter requirements for Hugo pages
- Admin UI: console URL
- Admin UI: add management features to existing admin pages
- Add a View account page for Admin UI
- Add screenshots
- Add Admin UI page to reference
- Alias reference/cli to influxctl until we expect more.
- Add key features list to influxctl reference
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
Jason Stirnaman
Copilot
Jason Stirnaman