@aigne/doc-smith 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.9.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.1-beta...v0.9.1) (2025-11-12)
+
+## [0.9.1-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.0...v0.9.1-beta) (2025-11-12)
+
+
+### Bug Fixes
+
+* polish openapi spec check condition ([#293](https://github.com/AIGNE-io/aigne-doc-smith/issues/293)) ([39632f5](https://github.com/AIGNE-io/aigne-doc-smith/commit/39632f5193fafbb658efe15c6f8e3eaf9a881b0d))
+* setup AFS storage for chat agent & improve chatbot prompt ([#292](https://github.com/AIGNE-io/aigne-doc-smith/issues/292)) ([5541e52](https://github.com/AIGNE-io/aigne-doc-smith/commit/5541e52333ad0b0b7a3280ee7c75cb745f49f535))
+
 ## [0.9.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.0-beta.1...v0.9.0) (2025-11-11)
 
 ## [0.9.0-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.0-beta...v0.9.0-beta.1) (2025-11-11)

package/README.md

@@ -80,7 +80,7 @@ Navigate to your project directory and run:
 
 ```bash
 # One command to generate your documentation
-aigne doc generate
+aigne doc create
 ```
 
 DocSmith will:
@@ -105,9 +105,9 @@ DocSmith supports multiple AI providers:
 
 ```bash
 # Switch models effortlessly
-aigne doc generate --model google:gemini-2.5-pro
-aigne doc generate --model anthropic:claude-sonnet-4-5
-aigne doc generate --model openai:gpt-4o
+aigne doc create --model google:gemini-2.5-pro
+aigne doc create --model anthropic:claude-sonnet-4-5
+aigne doc create --model openai:gpt-4o
 ```
 
 **🔑 Custom API Keys**
@@ -126,13 +126,13 @@ Configure your own API keys for direct provider access:
 
 ```bash
 # Smart generation with auto-configuration
-aigne doc generate
+aigne doc create
 
 # Force a complete regeneration of the documentation
-aigne doc generate --forceRegenerate
+aigne doc create --forceRegenerate
 
 # Generate with custom feedback
-aigne doc generate --feedback "Add more API examples and troubleshooting sections"
+aigne doc create --feedback "Add more API examples and troubleshooting sections"
 ```
 
 #### 🔄 Update Existing Documents
@@ -149,13 +149,13 @@ aigne doc update --docs overview.md --feedback "Add comprehensive FAQ section"
 
 ```bash
 # Interactive translation with smart language selection
-aigne doc translate
+aigne doc localize
 
 # Translate specific documents into multiple languages
-aigne doc translate --langs zh --langs ja --docs examples.md --docs overview.md
+aigne doc localize --langs zh --langs ja --docs examples.md --docs overview.md
 
 # Translate with a custom glossary for consistent terminology
-aigne doc translate --glossary @path/to/glossary.md --feedback "Use technical terminology consistently"
+aigne doc localize --glossary @path/to/glossary.md --feedback "Use technical terminology consistently"
 ```
 
 #### 🚀 Publishing & Deployment
@@ -300,4 +300,3 @@ This project is licensed under the **Elastic License 2.0**. See the [LICENSE](LI
 - ❌ **Restrictions**: You cannot offer DocSmith as a competing hosted service.
 
 [Learn more about the Elastic License 2.0](https://www.elastic.co/licensing/elastic-license)
-

package/agents/chat/chat-system.md

@@ -18,7 +18,7 @@ Interaction Guidelines:
 <skill_usage>
 - afs_xxx skills: AFS(AIGNE File System) skills provide capabilities to explore, read, write and manage files and virtual modules within the AIGNE environment.
   You can use these skills to access source files and other resources needed for documentation tasks.
-- listDocs: This skill lists all available documentation files in the system.
+- listDocuments: This skill lists all available documentation files in the system.
   You can use this skill to get an overview of existing documents before creating or modifying documentation. for documentation tasks,
   you should use this skill rather than afs_read to list documentation files.
 - generateDocument: This skill generates new documentation or updates existing documents structure based on user inputs and specifications,
@@ -30,3 +30,9 @@ Interaction Guidelines:
 - translate: This skill translates documentation content into different languages for localization purposes.
   You can use this skill to adapt documents for diverse audiences by providing translations in the required languages.
 </skill_usage>
+
+<output_requirements>
+- respect tools results and do not fabricate information, use tools results to answer user questions whenever possible
+- Use markdown format for all responses
+- Respond in the same language as the user
+</output_requirements>

package/agents/chat/index.mjs

@@ -0,0 +1,53 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { parse } from "yaml";
+
+await mkdir(".aigne/doc-smith", { recursive: true });
+const config = await readFile(".aigne/doc-smith/config.yaml", "utf-8")
+  .then((raw) => parse(raw))
+  .catch(() => null);
+
+const docsDir = config.docsDir || ".aigne/doc-smith/docs";
+
+export default {
+  type: "ai",
+  name: "chat",
+  description: "Start interactive document generation assistant",
+  instructions: {
+    url: "./chat-system.md",
+  },
+  input_key: "message",
+  afs: {
+    storage: {
+      url: "file:.aigne/doc-smith/.local/afs-storage.sqlite3",
+    },
+    modules: [
+      {
+        module: "system-fs",
+        options: {
+          path: ".",
+          mount: "/source",
+          description: "Project root directory for document generation",
+        },
+      },
+      {
+        module: "system-fs",
+        options: {
+          path: docsDir,
+          mount: "/docs",
+          description: "Generated documentation files directory",
+        },
+      },
+    ],
+  },
+  afs_config: {
+    inject_history: true,
+  },
+  skills: [
+    "./skills/list-documents.mjs",
+    "./skills/generate-document.yaml",
+    "./skills/update-document.yaml",
+    "../publish/index.yaml",
+    "../localize/index.yaml",
+    "../utils/exit.mjs",
+  ],
+};

package/agents/chat/skills/generate-document.yaml

@@ -10,6 +10,6 @@ input_schema:
   required:
     - feedback
 skills:
-  - url: ../../generate/index.yaml
+  - url: ../../create/index.yaml
     default_input:
       isChat: true

package/agents/{utils/list-docs.mjs → chat/skills/list-documents.mjs}

@@ -1,7 +1,7 @@
-import { getMainLanguageFiles } from "../../utils/docs-finder-utils.mjs";
-import init from "../init/index.mjs";
+import { getMainLanguageFiles } from "../../../utils/docs-finder-utils.mjs";
+import init from "../../init/index.mjs";
 
-export default async function listDocs(_, options) {
+export default async function listDocuments(_, options) {
   const config = await init({ checkOnly: true }, options);
 
   // Get all main language .md files in docsDir
@@ -12,4 +12,4 @@ export default async function listDocs(_, options) {
   };
 }
 
-listDocs.description = "List all available documentation files";
+listDocuments.description = "List all available documentation files";

package/agents/chat/skills/update-document.yaml

@@ -8,7 +8,7 @@ input_schema:
       type: array
       items:
         type: string
-      description: Documents to update, must from listDocs output
+      description: Documents to update, must from listDocuments output
     feedback:
       type: string
       description: Tell us what to change in this content

package/agents/{generate → create}/check-need-generate-structure.mjs

@@ -25,7 +25,7 @@ export default async function checkNeedGenerateStructure(
 
     if (choice === "later") {
       console.log(`\nConfiguration file: ${chalk.cyan("./.aigne/doc-smith/config.yaml")}`);
-      console.log("Review and edit your configuration, then run `aigne doc generate` to continue.");
+      console.log("Review and edit your configuration, then run `aigne doc create` to continue.");
 
       // In test environment, return a special result instead of exiting
       if (process.env.NODE_ENV === "test") {

package/agents/{generate → create}/index.yaml

@@ -1,9 +1,9 @@
 type: team
-name: generate
+name: create
 alias:
+  - generate
   - gen
-  - g
-description: Generate complete documentation for your project
+description: Create complete documentation for your project
 skills:
   - url: ../init/index.mjs
     default_input:

package/agents/init/check.mjs

@@ -6,7 +6,7 @@ export default async function checkNeedGenerate({ docsDir, locale, documentExecu
 
   if (mainLanguageFiles.length === 0) {
     console.log(
-      `No documents found in the docs directory. You can generate them with ${chalk.yellow("`aigne doc generate`")}`,
+      `No documents found in the docs directory. You can generate them with ${chalk.yellow("`aigne doc create`")}`,
     );
     process.exit(0);
   }

package/agents/init/index.mjs

@@ -423,11 +423,8 @@ async function _init(
     console.log(
       `\n✅ Setup complete! Your configuration has been saved to: ${chalk.cyan(filePath)}`,
     );
-    console.log(chalk.cyan("---"));
-    console.log(chalk.cyan(yamlContent));
-    console.log(chalk.cyan("---"));
     console.log("💡 You can edit this file at any time to change your settings.\n");
-    console.log(`🚀 To generate your documentation, run: ${chalk.cyan("aigne doc generate")}\n`);
+    console.log(`🚀 To generate your documentation, run: ${chalk.cyan("aigne doc create")}\n`);
 
     if (skipIfExists) {
       return loadConfig({ config: filePath, appUrl });

package/agents/{translate → localize}/index.yaml

@@ -1,5 +1,7 @@
 type: team
-name: translate
+name: localize
+alias:
+  - translate
 description: Translate documents into other languages
 skills:
   - url: ../init/index.mjs
@@ -28,11 +30,11 @@ skills:
   - url: ../utils/choose-docs.mjs
     default_input:
       isTranslate: true
-  - ../translate/choose-language.mjs
+  - ../localize/choose-language.mjs
   - type: team
     name: batchTranslateDocument
     skills:
-      - ../translate/translate-multilingual.yaml
+      - ../localize/translate-multilingual.yaml
     iterate_on: selectedDocs
     concurrency: 10
   - url: ../utils/check-feedback-refiner.mjs

package/agents/{translate → localize}/translate-multilingual.yaml

@@ -9,7 +9,7 @@ skills:
       - url: ../utils/find-user-preferences-by-path.mjs
         default_input:
           scope: translation
-      - ../translate/translate-document.yaml
+      - ../localize/translate-document.yaml
       - type: transform
         jsonata: |
           $merge([

package/agents/publish/publish-docs.mjs

@@ -52,11 +52,19 @@ export default async function publishDocs(
 
     // ----------------- main publish process flow -----------------------------
     // Check if DOC_DISCUSS_KIT_URL is set in environment variables
-    const useEnvAppUrl = !!(process.env.DOC_DISCUSS_KIT_URL || appUrl);
+    const useEnvAppUrl = !!(
+      process.env.DOC_SMITH_PUBLISH_URL ||
+      process.env.DOC_DISCUSS_KIT_URL ||
+      appUrl
+    );
 
     // Check if appUrl is default and not saved in config (only when not using env variable)
     const config = await loadConfigFromFile();
-    appUrl = process.env.DOC_DISCUSS_KIT_URL || appUrl || config?.appUrl;
+    appUrl =
+      process.env.DOC_SMITH_PUBLISH_URL ||
+      process.env.DOC_DISCUSS_KIT_URL ||
+      appUrl ||
+      config?.appUrl;
     const hasInputAppUrl = !!appUrl;
 
     let shouldSyncBranding = void 0;

package/agents/update/generate-diagram.yaml

@@ -2,10 +2,10 @@ type: team
 task_render_mode: collapse
 name: generateDiagram
 skills:
-  - ../generate/draw-diagram.yaml
-  - ../generate/wrap-diagram-code.mjs
+  - ../create/draw-diagram.yaml
+  - ../create/wrap-diagram-code.mjs
 reflection:
-  reviewer: ../generate/check-diagram.mjs
+  reviewer: ../create/check-diagram.mjs
   is_approved: isValid
   max_iterations: 5
   return_last_on_max_iterations: false

package/agents/utils/choose-docs.mjs

@@ -47,7 +47,7 @@ export default async function chooseDocs(
       if (mainLanguageFiles.length === 0) {
         throw new Error(
           `No documents found in the docs directory. You can generate them with ${chalk.yellow(
-            "`aigne doc generate`",
+            "`aigne doc create`",
           )}`,
         );
       }

package/agents/utils/find-item-by-path.mjs

@@ -76,7 +76,7 @@ export default async function findItemByPath(
       console.debug(error?.message);
       throw new Error(
         getActionText(
-          "Please run 'aigne doc generate' first to generate documents, then select which document to {action}",
+          "Please run 'aigne doc create' first to create documents, then select which document to {action}",
           docAction,
         ),
       );

package/agents/utils/post-generate.mjs

@@ -37,7 +37,7 @@ export default async function postGenerate({
 ✅ Documentation generated successfully! (\`${documentStructure.length}\` documents → \`${docsDir}\`)
 ${projectInfoMessage || ""}
 🚀 Next: Make your documentation live and generate a shareable link, run: \`aigne doc publish\`
-💡 Optional: Update specific document (\`aigne doc update\`) or refine documentation structure (\`aigne doc generate\`)
+💡 Optional: Update specific document (\`aigne doc update\`) or refine documentation structure (\`aigne doc create\`)
   `;
 
   // Shutdown mermaid worker pool to ensure clean exit

package/aigne.yaml

@@ -13,19 +13,19 @@ agents:
   - ./agents/init/index.mjs
 
   # Documentation Structure Generation
-  - ./agents/generate/generate-structure.yaml
-  - ./agents/generate/update-document-structure.yaml
-  - ./agents/generate/check-need-generate-structure.mjs
-  - ./agents/generate/refine-document-structure.yaml
-  - ./agents/generate/check-document-structure.yaml
-  - ./agents/generate/user-review-document-structure.mjs
-  - ./agents/generate/index.yaml
+  - ./agents/create/generate-structure.yaml
+  - ./agents/create/update-document-structure.yaml
+  - ./agents/create/check-need-generate-structure.mjs
+  - ./agents/create/refine-document-structure.yaml
+  - ./agents/create/check-document-structure.yaml
+  - ./agents/create/user-review-document-structure.mjs
+  - ./agents/create/index.yaml
 
   # Documentation Structure Tools
-  - ./agents/generate/document-structure-tools/add-document.mjs
-  - ./agents/generate/document-structure-tools/delete-document.mjs
-  - ./agents/generate/document-structure-tools/update-document.mjs
-  - ./agents/generate/document-structure-tools/move-document.mjs
+  - ./agents/create/document-structure-tools/add-document.mjs
+  - ./agents/create/document-structure-tools/delete-document.mjs
+  - ./agents/create/document-structure-tools/update-document.mjs
+  - ./agents/create/document-structure-tools/move-document.mjs
 
   # Document Content Generation & Updates
   - ./agents/update/batch-generate-document.yaml
@@ -42,10 +42,10 @@ agents:
 
 
   # Translation
-  - ./agents/translate/translate-document.yaml
-  - ./agents/translate/translate-multilingual.yaml
-  - ./agents/translate/choose-language.mjs
-  - ./agents/translate/index.yaml
+  - ./agents/localize/translate-document.yaml
+  - ./agents/localize/translate-multilingual.yaml
+  - ./agents/localize/choose-language.mjs
+  - ./agents/localize/index.yaml
 
   # Publishing
   - ./agents/publish/publish-docs.mjs
@@ -79,7 +79,6 @@ agents:
   - ./agents/utils/check-feedback-refiner.mjs
   - ./agents/utils/feedback-refiner.yaml
   - ./agents/utils/analyze-feedback-intent.yaml
-  - ./agents/utils/list-docs.mjs
 
   - ./agents/utils/document-title-streamline.yaml
   - ./agents/utils/streamline-document-titles-if-needed.mjs
@@ -88,7 +87,7 @@ agents:
 
   # User Preferences & Chat
   - ./agents/prefs/index.mjs
-  - ./agents/chat/index.yaml
+  - ./agents/chat/index.mjs
 
   # Documentation MCP Server
   - ./docs-mcp/get-docs-structure.mjs
@@ -106,18 +105,18 @@ agents:
   - ./agents/evaluate/code-snippet.mjs
 
   # Diagram
-  - ./agents/generate/merge-diagram.yaml
+  - ./agents/create/merge-diagram.yaml
   - ./agents/update/generate-diagram.yaml
   - ./agents/update/check-generate-diagram.mjs
   - ./agents/update/pre-check-generate-diagram.yaml
 cli:
-  chat: ./agents/chat/index.yaml
+  chat: ./agents/chat/index.mjs
   agents:
     - ./agents/init/index.mjs
-    - ./agents/generate/index.yaml
+    - ./agents/create/index.yaml
     - ./agents/update/index.yaml
     - ./agents/publish/index.yaml
-    - ./agents/translate/index.yaml
+    - ./agents/localize/index.yaml
     - ./agents/clear/index.yaml
     - ./agents/prefs/index.mjs
     - ./agents/evaluate/index.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"

package/utils/auth-utils.mjs

@@ -37,7 +37,8 @@ export async function getAccessToken(appUrl, ltToken = "") {
   const { hostname } = new URL(appUrl);
   const DOC_SMITH_ENV_FILE = getDocSmithEnvFilePath();
 
-  let accessToken = process.env.DOC_DISCUSS_KIT_ACCESS_TOKEN;
+  let accessToken =
+    process.env.DOC_SMITH_PUBLISH_ACCESS_TOKEN || process.env.DOC_DISCUSS_KIT_ACCESS_TOKEN;
 
   // Check if access token exists in environment or config file
   if (!accessToken) {
@@ -117,7 +118,7 @@ export async function getAccessToken(appUrl, ltToken = "") {
     });
 
     accessToken = result.accessKeySecret;
-    process.env.DOC_DISCUSS_KIT_ACCESS_TOKEN = accessToken;
+    process.env.DOC_SMITH_PUBLISH_ACCESS_TOKEN = accessToken;
 
     // Save the access token to config file
     const aigneDir = join(homedir(), ".aigne");

package/utils/history-utils.mjs

@@ -34,7 +34,7 @@ export function ensureGitRepo() {
       execSync("git init", { cwd, stdio: "ignore" });
 
       // Create .gitignore to exclude temporary files
-      const gitignore = "*.tmp\n";
+      const gitignore = "*.tmp\n.local/\n";
       writeFileSync(join(cwd, ".gitignore"), gitignore);
 
       // Initial commit

package/utils/openapi/index.mjs

@@ -1,22 +1,26 @@
 import { parse } from "yaml";
 
+function isMatchOpenAPISpec(content) {
+  if (!content) return false;
+  if (!(content.openapi || content.swagger)) return false;
+  if (!content.paths) return false;
+  if (!(content.info?.title && content.info?.version)) return false;
+  return true;
+}
+
 export function isOpenAPISpecFile(content) {
   const trimmedContent = content.trim();
   try {
     const parsed = parse(trimmedContent, {
       logLevel: "silent",
     });
-    if (parsed.openapi || parsed.swagger) {
-      return true;
-    }
+    return isMatchOpenAPISpec(parsed);
   } catch {
     //
   }
   try {
     const parsed = JSON.parse(trimmedContent);
-    if (parsed.openapi || parsed.swagger) {
-      return true;
-    }
+    return isMatchOpenAPISpec(parsed);
   } catch {
     //
   }

package/agents/chat/index.yaml

@@ -1,22 +0,0 @@
-type: ai
-name: chat
-description: Start interactive document generation assistant
-instructions:
-  url: ./chat-system.md
-input_key: message
-afs:
-  modules:
-    - module: system-fs
-      options:
-        path: .
-        mount: /source
-        description: Project root directory for document generation
-afs_config:
-  inject_History: true
-skills:
-  - ./skills/generate-document.yaml
-  - ./skills/update-document.yaml
-  - ../publish/index.yaml
-  - ../translate/index.yaml
-  - ../utils/exit.mjs
-  - ../utils/list-docs.mjs