chore: add AI agent groundwork

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,85 @@
+name: Bug Report
+description: Report a reproducible bug for this repository.
+title: "[Bug]: "
+labels:
+  - type:bug
+
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: Describe the bug clearly.
+    validations:
+      required: true
+
+  - type: textarea
+    id: current_behavior
+    attributes:
+      label: Current Behavior
+      description: What is happening now?
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected_behavior
+    attributes:
+      label: Expected Behavior
+      description: What should happen instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Provide exact reproduction steps.
+      placeholder: |
+        1.
+        2.
+        3.
+    validations:
+      required: true
+
+  - type: textarea
+    id: affected_area
+    attributes:
+      label: Affected Area
+      description: Mention routes, components, models, APIs, commands, or workflows affected.
+    validations:
+      required: false
+
+  - type: textarea
+    id: proposed_fix
+    attributes:
+      label: Proposed Fix
+      description: Optional implementation direction.
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance_criteria
+    attributes:
+      label: Acceptance Criteria
+      description: Define what must be true for this bug to be fixed.
+      placeholder: |
+        - [ ]
+        - [ ]
+    validations:
+      required: true
+
+  - type: textarea
+    id: docs_impact
+    attributes:
+      label: Documentation Impact
+      description: Does this require updates to fleetbase/fleetbase.io?
+    validations:
+      required: false
+
+  - type: textarea
+    id: api_impact
+    attributes:
+      label: API Reference Impact
+      description: Does this require updates to fleetbase/postman?
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,10 @@
+blank_issues_enabled: true
+
+contact_links:
+  - name: Fleetbase Documentation
+    url: https://fleetbase.io/docs
+    about: Read Fleetbase documentation.
+
+  - name: Fleetbase Website
+    url: https://fleetbase.io
+    about: Visit the Fleetbase website.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,73 @@
+name: Feature Request
+description: Request a new feature or enhancement.
+title: "[Feature]: "
+labels:
+  - type:feature
+
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: Describe the feature clearly.
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Use Case
+      description: What problem does this solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed_solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the desired implementation or behavior.
+    validations:
+      required: false
+
+  - type: textarea
+    id: affected_area
+    attributes:
+      label: Affected Area
+      description: Mention routes, components, models, APIs, commands, or workflows affected.
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance_criteria
+    attributes:
+      label: Acceptance Criteria
+      description: Define what must be true for this feature to be complete.
+      placeholder: |
+        - [ ]
+        - [ ]
+    validations:
+      required: true
+
+  - type: textarea
+    id: implementation_notes
+    attributes:
+      label: Implementation Notes
+      description: Optional technical direction for agents or maintainers.
+    validations:
+      required: false
+
+  - type: textarea
+    id: docs_impact
+    attributes:
+      label: Documentation Impact
+      description: Does this require updates to fleetbase/fleetbase.io?
+    validations:
+      required: false
+
+  - type: textarea
+    id: api_impact
+    attributes:
+      label: API Reference Impact
+      description: Does this require updates to fleetbase/postman?
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,60 @@
+## Summary
+
+Describe what changed and why.
+
+## Related Issue
+
+Closes #
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Refactor
+- [ ] Documentation
+- [ ] Test
+- [ ] Chore
+
+## Implementation Notes
+
+Explain the important implementation details.
+
+## Validation
+
+List commands run:
+
+- [ ] Tests
+- [ ] Lint
+- [ ] Build
+- [ ] Manual validation
+
+Command output / summary:
+
+```txt
+```
+
+## Documentation Impact
+
+- [ ] No documentation changes needed
+- [ ] Documentation updated in `fleetbase/fleetbase.io`
+- [ ] Documentation needed but not included
+
+## API Reference Impact
+
+- [ ] No API reference changes needed
+- [ ] Updated `fleetbase/postman`
+- [ ] API reference updates required but not included
+
+API reference notes:
+
+## Documentation Notes
+
+Describe documentation or API specification updates.
+
+## Risk
+
+Describe possible risks, migrations, compatibility issues, or rollout concerns.
+
+## Screenshots / Recordings
+
+Add screenshots or recordings for UI changes.

AGENTS.md

@@ -0,0 +1,136 @@
+# AI Agent Instructions
+
+## Repository Scope
+
+Fleetbase Postman and OpenAPI specification source for API collections, workflow examples, environments, and API reference generation.
+
+## Allowed Work
+
+- Updates to Postman/OpenAPI YAML collections, examples, workflow requests, and API documentation source files.
+- Lint fixes, collection organization, and examples that preserve real API behavior.
+- Spec updates that correspond to verified API behavior changes in Fleetbase modules.
+
+## Restricted Work
+
+- Committing real tokens, cookies, IDs, exported Vault data, or production credentials.
+- Inventing API behavior not backed by implementation or approved design.
+- Changing generated public documentation without coordinating required `fleetbase/fleetbase.io` regeneration or PRs.
+
+## Global Agent Rules
+
+- Do not merge pull requests.
+- Do not publish packages.
+- Do not rotate, expose, modify, or invent secrets.
+- Do not change production credentials or deployment configuration unless explicitly requested.
+- Do not perform large rewrites unless explicitly requested.
+- Prefer small, reviewable changes.
+- Preserve existing architecture and conventions.
+- Follow the repository's existing naming, formatting, and test patterns.
+- Add or update tests where practical.
+- If tests are not added, explain why in the PR.
+- Run available lint/test/build commands before finalizing the PR.
+- Include command output or a clear summary of validation performed.
+- If the issue is ambiguous, comment with questions instead of guessing.
+
+## Local Setup
+
+- `npm install`
+
+## Test Commands
+
+- Lint collections: `npm run postman:lint`
+- Run collections: `npm run postman:run`
+- Run scoped collections with scripts such as `npm run postman:run:fleetbase`, `npm run postman:run:core`, `npm run postman:run:storefront`, or `npm run postman:run:ledger`
+
+## Pull Request Rules
+
+- Work on a dedicated branch for each task.
+- Keep changes small and reviewable.
+- Stage only files related to the task.
+- Do not include unrelated local changes in commits.
+- Use clear PR titles and descriptions that explain what changed and why.
+- Link the related issue when one exists.
+- Include validation commands and a concise summary of results.
+- Explain any skipped tests, missing coverage, or known follow-up work.
+- Call out documentation and API reference impact using the PR template.
+- Do not merge the PR after opening it.
+
+## Documentation Rules
+
+Some changes require documentation updates in `fleetbase/fleetbase.io`.
+
+Some API-related changes additionally require updates to API specification files in `fleetbase/postman`.
+
+Update or create documentation when a change affects:
+
+- user-facing behavior
+- configuration
+- installation steps
+- environment variables
+- API behavior
+- request/response schemas
+- authentication behavior
+- extension behavior
+- permissions or IAM behavior
+- billing, invoicing, wallets, or gateway behavior
+- developer workflows
+- CLI commands
+- mobile app workflows
+- onboarding flows
+- breaking changes
+- deprecated behavior
+
+If API behavior changes, the agent must determine whether corresponding specification updates are needed in `fleetbase/postman`.
+
+Examples include:
+
+- new endpoints
+- modified endpoints
+- payload changes
+- validation changes
+- authentication changes
+- response schema changes
+- enum changes
+- new query parameters
+- deprecated API behavior
+
+If API specification files are updated in `fleetbase/postman`, the agent should also determine whether a documentation PR or regeneration step is required in `fleetbase/fleetbase.io`.
+
+If documentation should be updated but cannot be updated in the same PR, the agent must:
+
+1. mention this clearly in the PR description;
+2. add a `needs-docs` label if available;
+3. reference the expected documentation area in `fleetbase/fleetbase.io`;
+4. reference any required specification updates in `fleetbase/postman`.
+
+## Escalation Rules
+
+Stop and request human clarification when:
+
+- the requested behavior is ambiguous or conflicts with existing architecture;
+- the change would alter public APIs, authentication, permissions, billing, financial records, or production configuration;
+- secrets, credentials, signing assets, deployment settings, or release automation are involved;
+- the safest implementation requires a large rewrite or broad cross-repository coordination;
+- tests fail for reasons that are not clearly related to the change;
+- documentation or API specification ownership is unclear.
+
+## Recommended Labels
+
+Use these labels when they are available:
+
+- `type:bug`
+- `type:feature`
+- `type:docs`
+- `type:refactor`
+- `type:chore`
+- `agent:ready`
+- `agent:blocked`
+- `agent:in-progress`
+- `needs-docs`
+- `needs-api-spec`
+- `needs-human-review`
+- `needs-product-decision`
+- `priority:p0`
+- `priority:p1`
+- `priority:p2`
+- `priority:p3`