Merge branch 'main' into ready

.github/pull_request_template.md

@@ -0,0 +1,35 @@
+# Pull Request
+
+## What was broken
+
+<!-- Describe the user-visible or maintainer-visible problem. -->
+
+## Root cause
+
+<!-- Explain the specific reason this happened. -->
+
+## What changed
+
+<!-- List the focused code or documentation changes in this PR. -->
+
+## Validation
+
+- [ ] I searched open and recently closed upstream PRs for overlapping work.
+- [ ] I recorded the exact tests or checks I ran below.
+- [ ] If validation was blocked, I explained the blocker clearly.
+
+### Tests / checks run
+
+- `...`
+
+## Risk / follow-up notes
+
+<!-- Note residual risk, rollout considerations, or deliberate follow-up work. -->
+
+## Related issues / PRs
+
+<!-- Example: Fixes #1234, Relates to #1439 -->
+
+## Fork safety note
+
+<!-- If this branch lives on a fork with GitHub Actions workflows, mention whether maintainer edits were enabled and whether that is safe for this branch. -->

CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing to Agent Zero
+
+This file is the GitHub-visible entry point for contributors.
+
+For the full contribution workflow, start with:
+
+- [`docs/guides/contribution.md`](docs/guides/contribution.md) — fork, sync, branch, validation, and pull-request flow
+- [`docs/developer/sharing-and-safety.md`](docs/developer/sharing-and-safety.md) — how to decide whether a change should go upstream, into a plugin repository, into a skills repository, or remain private
+- [`docs/developer/plugins.md`](docs/developer/plugins.md) — plugin structure and Plugin Index submission
+- [`docs/developer/contributing-skills.md`](docs/developer/contributing-skills.md) — skill authoring and publication
+
+## Quick rules
+
+- Search open and recently closed upstream PRs before opening a new one.
+- Use the branch currently adopted by comparable active upstream PRs or explicit maintainer guidance.
+- Keep one focused change per PR whenever practical.
+- Keep the source branch available on your fork until the PR is merged or intentionally closed.
+- Include exact tests run, or clearly explain why validation was blocked.
+- Do not include secrets, `.env` files, local virtual environments, or machine-specific artifacts in a PR.
+
+## Choosing the right place to share work
+
+- **Core bugfix or docs for Agent Zero itself:** contribute back to `agent0ai/agent-zero` from a public fork.
+- **Community plugin:** publish the plugin in its own public repository, then submit it to `agent0ai/a0-plugins`.
+- **Reusable skill:** contribute it to Agent Zero's `skills/` tree or publish it in a dedicated public repository/collection.
+- **Private experiment, customer-specific code, local R&D, or sensitive material:** keep it out of public forks and upstream PRs.
+
+If you're unsure, use the decision guide in [`docs/developer/sharing-and-safety.md`](docs/developer/sharing-and-safety.md).

docs/developer/sharing-and-safety.md

@@ -0,0 +1,129 @@
+# Sharing and Safety Guide
+
+This guide helps contributors decide **what to share**, **where to share it**, and **what must stay private**.
+
+## Start with the decision tree
+
+### 1. Is this change meant for the Agent Zero core repository?
+
+Use the main `agent-zero` contribution flow when the change directly improves the framework itself, for example:
+
+- a bugfix in `webui/`, `helpers/`, `api/`, `tools/`, `extensions/`, or `docs/`
+- a test that belongs with core framework behavior
+- documentation for built-in functionality
+
+If yes:
+
+1. Fork `agent0ai/agent-zero` publicly.
+2. Add `upstream` to your local clone.
+3. Sync from `upstream/main` (or the currently used upstream target branch).
+4. Create a focused branch.
+5. Open the PR across forks.
+
+See [`../guides/contribution.md`](../guides/contribution.md) for the detailed workflow.
+
+### 2. Is this a community plugin?
+
+Use a **dedicated public plugin repository** when the work is a standalone plugin that users can install independently.
+
+Typical signals:
+
+- it lives cleanly under `usr/plugins/<plugin_name>/`
+- it has its own `plugin.yaml`
+- it can evolve independently from the core repository
+- it should be discoverable in the Plugin Hub
+
+If yes:
+
+1. Put the plugin contents at the root of its own repository.
+2. Include `plugin.yaml`, `README.md`, and `LICENSE`.
+3. Test it locally from `usr/plugins/`.
+4. Submit its `index.yaml` entry to `agent0ai/a0-plugins`.
+
+See [`plugins.md`](plugins.md) for the Plugin Index rules and packaging details.
+
+### 3. Is this a reusable skill?
+
+Use the **skills workflow** when the work is mainly procedural knowledge in `SKILL.md` form.
+
+Typical signals:
+
+- it teaches the agent how to perform a task
+- it is portable across Agent Zero, Cursor, Claude Code, or Copilot-style ecosystems
+- it lives naturally under `usr/skills/` during development
+
+If yes:
+
+1. Develop it locally in `usr/skills/`.
+2. Validate the structure and examples.
+3. Move it into `skills/` for an Agent Zero contribution, or publish it in a dedicated public repository/collection.
+
+See [`contributing-skills.md`](contributing-skills.md) for the authoring standard.
+
+### 4. Should this stay private?
+
+Keep the work **out of public forks and upstream PRs** when it includes any of the following:
+
+- credentials, tokens, API keys, `.env` files, or customer secrets
+- local-only experiments, snapshots, or temporary branch archaeology
+- customer-specific logic or data
+- machine-specific configuration, caches, local virtual environments, or editor debris
+- plugin or skill prototypes that are not ready for public review
+
+If yes, keep it in a private repository, in `usr/`, or outside the public contribution path entirely.
+
+## Safe publication rules
+
+### Public forks and pull requests
+
+- Use a **public, pushable fork** for any branch that may become the head branch of an upstream PR.
+- Keep the source branch alive until the PR is merged or intentionally closed.
+- Search open and recently closed upstream PRs before opening a new one.
+- Choose the base branch from current upstream practice; do not hardcode `development` if active comparable PRs target `main`.
+- Record the exact tests you ran.
+
+### Allow edits from maintainers
+
+GitHub lets you allow maintainers to edit a branch on your fork.
+
+If the fork branch contains GitHub Actions workflows, GitHub may show **"Allow edits and access to secrets by maintainers"**. Treat this carefully:
+
+- only enable it when you are comfortable with maintainers editing workflow files on that branch
+- do not leave sensitive values or private automation in a fork branch you plan to share publicly
+
+### Files that usually do not belong in public contributions
+
+- `.env`
+- `.venv/`
+- editor settings such as `.vscode/settings.json`
+- temporary notes, scratch files, or machine-specific backups
+- unrelated formatting churn
+- private reports or internal strategy docs
+
+## Recommended repository model
+
+For teams or maintainers juggling both private R&D and public contributions, this split keeps things sane:
+
+1. **Private workspace or backup repository**
+   - plugin experiments
+   - customer-specific work
+   - snapshots and branch archaeology
+   - internal notes and strategy
+
+2. **Clean fix-only clone for upstream-facing work**
+   - only branches that may become public PRs
+   - synced from upstream
+   - no snapshots, no unrelated experiments
+
+3. **Public fork used only for PR head branches**
+   - only focused, reviewable public branches
+   - no internal scratch branches
+
+## Before you publish anything
+
+- Confirm the work belongs in the chosen publication path.
+- Remove secrets and local-only artifacts.
+- Check for overlapping upstream work.
+- Make sure the diff is narrow and reviewer-friendly.
+- Verify the test evidence you plan to mention.
+- Make sure the branch source is public if it will back an upstream PR.

docs/guides/contribution.md

@@ -14,18 +14,41 @@ Contributions to improve Agent Zero are very welcome!  This guide outlines how t
 
 ## Making Changes
 
-* **Code Style:** Follow the existing code style. Agent Zero generally follows PEP 8 conventions.
-* **Documentation:**  Update the documentation if your changes affect user-facing functionality. The documentation is written in Markdown.
-* **Commit Messages:**  Write clear and concise commit messages that explain the purpose of your changes.
+- **Code Style:** Follow the existing code style. Agent Zero generally follows PEP 8 conventions.
+- **Documentation:** Update the documentation if your changes affect user-facing functionality. The documentation is written in Markdown.
+- **Commit Messages:** Write clear and concise commit messages that explain the purpose of your changes.
 
 ## Submitting a Pull Request
 
 1. **Push Your Branch:** Push your branch to your forked repository on GitHub.
 2. **Create a Pull Request:** Create a pull request from your branch to the appropriate branch in the main Agent Zero repository.
-   * Target the `development` branch.
+   - Search open and recently closed upstream PRs for overlapping work before opening a new one.
+   - Target the branch currently used for comparable active upstream contributions or explicit maintainer guidance. Do not assume `development` is always correct.
+   - Keep the source branch available on your fork until the pull request is merged or intentionally closed.
 3. **Provide Details:** In your pull request description, clearly explain the purpose and scope of your changes. Include relevant context, test results, and any other information that might be helpful for reviewers.
 4. **Address Feedback:**  Be responsive to feedback from the community. We love changes, but we also love to discuss them!
 
+## Working With Forks Safely
+
+When contributing from a fork, prefer the standard GitHub flow:
+
+1. **Fork the repository publicly** if the branch may become the head branch of an upstream pull request.
+2. **Add an `upstream` remote** that points to `agent0ai/agent-zero`.
+3. **Sync your fork regularly** before starting new work so your branch starts from the current upstream target branch.
+4. **Create one focused branch per change** (for example, one bugfix, one plugin, or one docs update).
+5. **Open the pull request across forks** by explicitly selecting the upstream base repository/branch and your fork/compare branch.
+
+If your fork contains GitHub Actions workflows, be careful with GitHub's "Allow edits and access to secrets by maintainers" option. Only enable it when you are comfortable with maintainers editing workflow files on the fork branch.
+
+## Choosing The Right Publication Path
+
+- **Core bugfixes and docs for Agent Zero itself:** prepare them in a clean fork/clone of `agent-zero` and open a PR back to the upstream repository.
+- **Community plugins:** publish the plugin in its own public repository, then submit its `index.yaml` entry to `agent0ai/a0-plugins` as described in `../developer/plugins.md`.
+- **Skills:** develop locally in `usr/skills/`, then move stable skills to `skills/` for Agent Zero contributions or publish them in a dedicated public repository/collection.
+- **Private experiments, credentials, local R&D, or customer-specific assets:** keep them out of public forks and upstream pull requests.
+
+For a contributor-focused decision guide that covers fixes, plugins, skills, and what should stay private, see `../developer/sharing-and-safety.md`.
+
 ## Documentation Stack
 
 - The documentation is built using Markdown. We appreciate your contributions even if you don't know Markdown, and look forward to improve Agent Zero for everyone's benefit.