feat(#801): Make-cht-conf-AI-agents-friendly

[Hendrixx-RE]

Description

I have implemented a comprehensive set of features to make cht-conf more "AI-agent friendly," ensuring that coding agents (and human developers) have better documentation, clearer instructions, and powerful inspection tools.

#801

1. New Local Documentation (src/docs/cht-conf/)
   I added a dedicated documentation folder that is bundled with the tool. This allows AI agents to read guides directly from the file system without
   needing internet access.

• actions.md: A full reference guide for all 42+ cht-conf actions, grouped by category (Upload, Backup, Convert, etc.).
• project-structure.md: Defines the strict directory layout required for CHT projects (e.g., where to put contact forms vs app forms).
• form-conventions.md: Documents CHT-specific XLSForm patterns like db-doc references and contact-summary field access.

2. Agent Instruction Templates (src/lib/agent-templates.js)
   I created a new shared library to store the templates for:

• AGENTS.md: A high-level project guide for AI tools.
• CLAUDE.md: Specific personality and behavioral instructions for Claude-based agents.

3. Automated Agent Setup

• Modified src/fn/initialise-project-layout.js: Updated the standard project initialization to automatically generate AGENTS.md and CLAUDE.md whenever a new project is created (cht initialise-project-layout).
• Added src/fn/agents-md.js: Created a new action so that developers with existing projects can run cht agents-md to generate these files instantly.

4. Documentation Sync Tool

• Added src/fn/update-docs.js: Implemented an action (cht update-docs) that fetches the latest official Markdown guides from the medic/cht-docs GitHub repository and stores them in the user's home directory (~/.cht-conf/docs/).

5. Instance Inspection Suite (src/fn/inspect-*.js)
   I implemented 9 new "Inspect" commands that allow an agent to query a running CHT instance and "see" its state from the terminal:

• inspect-forms: Lists all forms currently on the server.
• inspect-form : Shows the fields, calculations, and media of a specific form.
• inspect-settings-diff: Compares local app_settings.json with what is actually deployed on the server.
• inspect-tasks / inspect-targets: Lists the current task/target logic from the server.
• inspect-hierarchy: Displays a visual tree of the contact hierarchy.
• inspect-transitions: Shows transitions status and highlights any deprecated ones.
• inspect-replication: Reports live CouchDB replication progress.
• inspect-errors: Pulls the most recent error logs directly from the medic-logs database.

6. Technical Core Updates

• Modified src/lib/api.js: Exposed a generic api.get() method so that the new inspection and documentation tools can make authorized requests to the CHT instance.
• Modified README.md: Added a new "AI Agent Support" section documenting all these new capabilities.
• Linter Fixes: Manually added eslint-disable no-console to the inspection commands (since their primary job is to print to the terminal) and fixed indentation across all new files to maintain the project's strict 2-space style.

Orchestration was done by me with the help of claude.Any suggestions or features to add would be appreciated!

Code review items

• Readable: Concise, well named, follows the style guide, documented if necessary.
• Documented: Configuration and user documentation on cht-docs
• Tested: Unit and/or integration tests where appropriate
• Backwards compatible: Works with existing data and configuration. Any breaking changes documented in the release notes.

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[Hendrixx-RE]

@jkuester ?

[jkuester]

@inromualdo @sugat009 would you all have capacity to look into this PR? If needed maybe we break it into smaller more tightly scoped ones?

[sugat009]

@inromualdo, reviewing #815 against your spec in #801. Two things on the spec direction:

1. Audience: in your experience, are LLMs actually being used on CHT configuration projects? Most of the ones I see are private and government-led, where LLM use seems unlikely. Want to make sure we're not generating boilerplate into projects that won't read it.

2. The bundled-docs portion of the spec may be redundant. We already have a public deepwiki MCP for cht-conf (93 documents covering every action, core library, contact summary, nools, and configuration page) and the cht-kapa-docs MCP for the CHT docs content, plus the public docs site at docs.communityhealthtoolkit.org. For agents that support MCP (most major ones do), all the documentation Phase 1 wanted to bundle is already accessible without shipping anything in the npm package, and stays fresh automatically. Worth seriously reconsidering whether bundling is needed at all.

---

@Hendrixx-RE, on the implementation:

1. The generated AGENTS.md/CLAUDE.md are basically pointer files ("refer to the bundled documentation", "use cht commands"). Anything in there is stuff an agent would discover anyway by listing the directory or running cht --help. The file adds zero signal over having no file at all. For the AGENTS.md standard to actually pay off, the file has to encode things the agent can't easily derive: the specific gotchas Romuald listed in the issue (forms in wrong dirs, missing .properties.json, invalid tasks.js schemas), project-specific conventions, things that are wrong but compile.

[Hendrixx-RE]

Good point on the second argument,I didnt think about it that way.So is there any particular convention you have in mind?

[Hendrixx-RE]

Made some changes to remove the redundant lines and added some of the agent pitfalls that I found.
@sugat009 ?

[sugat009]

@Hendrixx-RE, before another push, can we hold here until @inromualdo replies to the two scope questions I left on May 5? Both are about the spec itself (whether the LLM audience exists for CHT config projects, and whether bundled docs are redundant given the existing deepwiki + kapa-docs MCPs), so the answers will shape whether parts of this PR even need to exist. Don't want you iterating on a direction that might get scoped down once the spec is settled.

[Hendrixx-RE]

Got it