Add AGENTS.md files to provide guidelines for project and packages

AGENTS.md

@@ -0,0 +1,87 @@
+# AGENTS.MD: AI Collaboration Guide
+
+## Project Overview & Purpose
+
+* MarkBind is a static site generator optimized for content-heavy instructional websites (e.g., courses, tutorials, documentation). It converts Markdown-like syntax into rich, interactive HTML websites.
+* Business Domain: Documentation, Education, Static Site Generation (SSG).
+
+## Core Technologies & Stack
+
+* Languages:
+    * TypeScript (Backend/Core logic, `packages/core`)
+    * JavaScript (Legacy scripts, CLI, Webpack configs)
+    * Vue.js 3 (Frontend components, `packages/vue-components`, `packages/core-web`)
+* Frameworks & Runtimes:
+    * Node.js (Runtime)
+    * Vue 3 (Frontend Framework)
+    * Jest (Testing)
+* Key Libraries/Dependencies:
+    * `markdown-it` (Markdown parsing)
+    * `nunjucks` (Templating)
+    * `commander` (CLI interface)
+    * `webpack` (Asset bundling)
+* Package Manager(s):
+    *   `npm` (Workspaces enabled)
+    *   `lerna` (Monorepo orchestration)
+
+## Architectural Patterns
+
+* Overall Architecture: Monorepo structure managed by Lerna. Separates concerns into:
+    *   CLI (`packages/cli`): Command-line interface and orchestration.
+    *   Core (`packages/core`): Main logic for parsing and generating sites.
+    *   Core-Web (`packages/core-web`): Client-side assets and build configuration.
+    *   Vue Components (`packages/vue-components`): UI library for the generated sites.
+* Directory Structure Philosophy:
+    *   `packages/`: Contains all monorepo packages.
+    *   `docs/`: Documentation site content (dogfooding MarkBind).
+    *   `scripts/`: Maintainance and utility scripts.
+
+## Coding Conventions & Style Guide
+
+* Formatting:
+    *   Indentation: 2 spaces.
+    *   Style: Follows `airbnb-base` and `airbnb-typescript`.
+    *   Enforced via ESLint (`.eslintrc.js`).
+* Naming Conventions:
+    *   Variables/Functions: camelCase (`processMarkdown`).
+    *   Classes: PascalCase (`SiteDeployManager`).
+    *   Files: kebab-case preferred for new files, though consistency with existing structure is paramount.
+
+## Key Files & Entrypoints
+
+* CLI Entry: `packages/cli/index.js`
+* Core Entry: `packages/core/index.js`
+* Monorepo Config: `lerna.json`
+* Lint Config: `.eslintrc.js`
+
+## Development & Testing Workflow
+
+* Local Development Environment:
+    *   Initial Setup: Run `npm run setup` to install dependencies, clean artifacts, and bootstrap the monorepo.
+    *   Backend (Core): Run `npm run dev` in the root to watch/recompile TypeScript. Otherwise, run `npm run build:backend` to compile TypeScript.
+    *   Frontend: Run `markbind serve -d` to enable hot reloading of client assets.
+    *   Troubleshooting: Run `npm run clean` to remove compiled artifacts if you encounter "orphaned file" issues (e.g., after renaming `.ts` files).
+    *   Warning: Do NOT build full release bundles (`npm run build:web`) manually unless releasing.
+* Testing:
+    *   Run `npm test` for all tests.
+    *   Run `npm run updatetest` to update test snapshots.
+    *   Localized Testing: Run tests in specific package directories (`packages/core`, etc.) for efficiency.
+* CI/CD Process: GitHub Actions (`.github/workflows`) handle testing and linting on PRs.
+
+## Specific Instructions for AI Collaboration
+
+* Contribution:
+    *   Follow the "Do" and "Don't" lists in package-specific `AGENTS.md` files.
+    *   Ensure small diffs and meaningful commit messages.
+* Security:
+    *   Do not hardcode secrets.
+    *   Validate inputs in CLI and Core logic.
+* Dependencies:
+    *   Use `npm` workspaces.
+    *   Do not add heavy dependencies without strong justification.
+
+See each package's `AGENTS.md` for specific guidelines:
+* [CLI](packages/cli/AGENTS.md)
+* [Core](packages/core/AGENTS.md)
+* [Core Web](packages/core-web/AGENTS.md)
+* [Vue Components](packages/vue-components/AGENTS.md)

packages/cli/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.MD: CLI Package Guide
+
+The `markbind-cli` package handles command-line operations, argument parsing, and orchestrates the build process by invoking `@markbind/core`.
+
+## Core Technologies
+*   **Language:** JavaScript (Node.js)
+*   **Libraries:** `commander` (CLI), `winston` (Logging).
+
+## Key Files
+*   `index.js`: Main entry point.
+*   `test/functional/`: Functional tests (crucial for CLI verification).
+
+## Development Workflow
+*   **Testing:**
+    *   `npm test`: Runs unit and functional tests.
+    *   `npm run updatetest`: Updates functional test snapshots.
+*   **Dependencies:** Relies on `@markbind/core` and `@markbind/core-web`.
+
+## Coding & Contribution Rules
+### Do
+- Use `commander` for new CLI commands/options.
+- Ensure `index.js` remains the main entry point.
+- Use `winston` for logging.
+
+### Don't
+- Do not put core site generation logic here; delegate to `@markbind/core`.

packages/core-web/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.MD: Core Web Package Guide
+
+## Package Overview
+The `@markbind/core-web` package manages client-side assets (JS/CSS) and the webpack build process.
+
+## Core Technologies
+*   **Language:** JavaScript, Vue
+*   **Build Tool:** Webpack (with `babel`, `vue-loader`).
+
+## Key Files
+*   `webpack.build.js`: Webpack configuration.
+*   `src/`: Client-side JavaScript/Vue entry points.
+
+## Development Workflow
+*   **Editing Frontend Features:**
+    *   **Recommended**: Run `markbind serve -d` to compile bundles and enable hot reloading.
+    *   **Release Only**: `npm run build:client` / `npm run build:server`.
+    *   **Do NOT** build full bundles manually during development.
+
+## Coding & Contribution Rules
+### Do
+- Use Webpack for bundling assets.
+- Ensure `babel` transforms are correctly configured for target browsers.

packages/core/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.MD: Core Package Guide
+
+## Package Overview
+The `@markbind/core` package contains the core logic for processing Markdown, plugins, and generating the final HTML output.
+
+## Core Technologies
+*   **Language:** TypeScript
+*   **Libraries:** `markdown-it`, `nunjucks`, `fs-extra`.
+
+## Key Files
+*   `src/index.ts`: Main entry point.
+*   `src/plugins/`: Custom MarkBind plugins.
+
+## Development Workflow
+*   **Compilation:**
+    *   `npm run dev` (in Root): Useful for watching changes.
+    *   `npm run compile`: Manual TypeScript compilation.
+*   **Testing:**
+    *   `npm run test`: Runs Jest tests.
+
+## Coding & Contribution Rules
+### Do
+- Use TypeScript for all new logic.
+- Implement `markdown-it` plugins for new syntax features.
+- Keep processing logic separate from UI generation where possible.
+
+### Don't
+- Do not mix pure markdown processing with file I/O if avoidable (make logic testable).

packages/vue-components/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.MD: Vue Components Package Guide
+
+## Package Overview
+The `@markbind/vue-components` package contains the Vue 3 component library utilized by MarkBind sites.
+
+## Core Technologies
+*   **Framework:** Vue 3
+*   **Style:** Bootstrap / Scoped CSS
+
+## Key Files
+*   `src/*.vue`: Vue components.
+*   `src/__tests__/`: Component tests.
+
+## Development Workflow
+*   **Testing:**
+    *   `npm test`: Run component tests.
+    *   `npm run updatetest`: Snapshot updates.
+    *   Use `markbind serve -d` in a test site to visually verify components.
+
+## Coding & Contribution Rules
+### Do
+- **Vue Options API**: Maintain consistency with existing components (e.g., `Box.vue`).
+- **Scoped CSS**: Prevent style leakage.
+- **Props**: Define clear props with types and defaults.
+
+### Don't
+- **Composition API**: Avoid unless explicitly approved.
+- **Hardcoding**: Use props or bootstrap tokens for colors/styles.