From 45bba3cd34d51480e21b624202fb7f760c950be9 Mon Sep 17 00:00:00 2001 From: gosunuts Date: Fri, 28 Aug 2026 14:05:44 +0900 Subject: [PATCH 1/5] docs: add CONTRIBUTING.md for AI accessibility AGENTS.md stays the core implementation guide. Contribution policy lives here: agents may file access-surface issues without assignment; repeated skill instructions are bugs. Merge bar is #346. Core protocol stays under AGENTS.md. Closes #327 --- CONTRIBUTING.md | 15 +++++++++++++++ README.md | 5 +---- README.zh-CN.md | 5 +---- 3 files changed, 17 insertions(+), 8 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..c2493f0f4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,15 @@ +# Contributing + +`AGENTS.md` is the core implementation and architecture guide. This file is contribution policy. The merge bar for agent-facing code is [#346](https://github.com/gosuda/portal-tunnel/issues/346). + +## Pull requests + +Fork, branch, make a focused change with tests or docs, open a PR. + +## AI accessibility + +Agents may file issues, reviews, and small PRs without prior assignment when the change is CLI, logs, diagnostics, docs, skills, or integration friction. + +Every repeated agent instruction is a candidate accessibility bug. Fix the Portal surface and delete the instruction. Do not document another workaround. + +Protocol, cryptography, trust, identity, transport, and architecture stay under `AGENTS.md`. Do not add a plugin workflow engine, finding store, or feedback CLI ([#331](https://github.com/gosuda/portal-tunnel/issues/331)). diff --git a/README.md b/README.md index 1a22e9c1c..6667a58df 100644 --- a/README.md +++ b/README.md @@ -229,10 +229,7 @@ relay, open a pull request to add your relay URL to `registry.json`. ## Contributing -1. Fork the repository. -2. Create a feature branch (`git checkout -b feature/amazing-feature`). -3. Make the change with focused tests or docs. -4. Open a pull request. +See [CONTRIBUTING.md](CONTRIBUTING.md). ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index 856e5bf1e..8f17b7755 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -188,10 +188,7 @@ https://raw.githubusercontent.com/gosuda/portal-tunnel/main/registry.json ## 贡献 -1. Fork 这个仓库。 -2. 创建功能分支（`git checkout -b feature/amazing-feature`）。 -3. 用聚焦的测试或文档完成修改。 -4. 打开 pull request。 +见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 From 8c898ddd3bc61aec216186871c932efb943192ad Mon Sep 17 00:00:00 2001 From: gosunuts Date: Fri, 28 Aug 2026 14:08:07 +0900 Subject: [PATCH 2/5] docs: clarify contribution policy boundaries --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2493f0f4..556624700 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -`AGENTS.md` is the core implementation and architecture guide. This file is contribution policy. The merge bar for agent-facing code is [#346](https://github.com/gosuda/portal-tunnel/issues/346). +`AGENTS.md` is the core implementation guide. Architecture, product behavior, and design rationale belong in `docs/architecture.md` and `docs/adr/README.md`. This file is contribution policy. The merge bar for agent-facing changes is [#346](https://github.com/gosuda/portal-tunnel/issues/346). ## Pull requests @@ -12,4 +12,4 @@ Agents may file issues, reviews, and small PRs without prior assignment when the Every repeated agent instruction is a candidate accessibility bug. Fix the Portal surface and delete the instruction. Do not document another workaround. -Protocol, cryptography, trust, identity, transport, and architecture stay under `AGENTS.md`. Do not add a plugin workflow engine, finding store, or feedback CLI ([#331](https://github.com/gosuda/portal-tunnel/issues/331)). +Core semantic changes require stronger justification under [#346](https://github.com/gosuda/portal-tunnel/issues/346) and the repository's architecture rules. Generic feedback orchestration stays outside this repository ([#331](https://github.com/gosuda/portal-tunnel/issues/331)). \ No newline at end of file From adf8403ad6716bf8f06baf4441ccee8fc809838d Mon Sep 17 00:00:00 2001 From: gosunuts Date: Fri, 28 Aug 2026 14:10:22 +0900 Subject: [PATCH 3/5] docs: distinguish human and AI contributions --- CONTRIBUTING.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 556624700..82d2f88e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,17 @@ # Contributing -`AGENTS.md` is the core implementation guide. Architecture, product behavior, and design rationale belong in `docs/architecture.md` and `docs/adr/README.md`. This file is contribution policy. The merge bar for agent-facing changes is [#346](https://github.com/gosuda/portal-tunnel/issues/346). +`AGENTS.md` is the core implementation guide. Architecture, product behavior, and design rationale belong in `docs/architecture.md` and `docs/adr/README.md`. This file is contribution policy. -## Pull requests +## Human contributions -Fork, branch, make a focused change with tests or docs, open a PR. +Human contributors may propose issues, reviews, and pull requests across the project. -## AI accessibility +Fork, branch, make a focused change with tests or docs, and open a PR. Changes to protocol semantics, cryptography, trust, identity, transport, or architecture should explain the design rationale and follow `AGENTS.md` and the repository architecture rules. -Agents may file issues, reviews, and small PRs without prior assignment when the change is CLI, logs, diagnostics, docs, skills, or integration friction. +## AI contributions + +AI-generated issues, reviews, and small PRs are explicitly welcome without prior assignment when they improve CLI behavior, logs, diagnostics, docs, skills, or integration accessibility. The merge bar for agent-facing changes is [#346](https://github.com/gosuda/portal-tunnel/issues/346). Every repeated agent instruction is a candidate accessibility bug. Fix the Portal surface and delete the instruction. Do not document another workaround. -Core semantic changes require stronger justification under [#346](https://github.com/gosuda/portal-tunnel/issues/346) and the repository's architecture rules. Generic feedback orchestration stays outside this repository ([#331](https://github.com/gosuda/portal-tunnel/issues/331)). \ No newline at end of file +Agent usability alone is not a reason to change protocol, cryptography, trust, identity, transport, or architecture semantics. Core changes follow the same repository rules as human contributions. Generic feedback orchestration stays outside this repository ([#331](https://github.com/gosuda/portal-tunnel/issues/331)). \ No newline at end of file From 02024b15bffa9d53341c126b050c2e2eeb182ff0 Mon Sep 17 00:00:00 2001 From: gosunuts Date: Fri, 28 Aug 2026 14:16:43 +0900 Subject: [PATCH 4/5] docs: distinguish human and AI contributions --- CONTRIBUTING.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 82d2f88e5..f38f0e898 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,16 +2,22 @@ `AGENTS.md` is the core implementation guide. Architecture, product behavior, and design rationale belong in `docs/architecture.md` and `docs/adr/README.md`. This file is contribution policy. -## Human contributions +## For Human Contributors -Human contributors may propose issues, reviews, and pull requests across the project. +Thank you for contributing to Portal. -Fork, branch, make a focused change with tests or docs, and open a PR. Changes to protocol semantics, cryptography, trust, identity, transport, or architecture should explain the design rationale and follow `AGENTS.md` and the repository architecture rules. +Human review and judgment are especially important in the parts of the project where correctness depends on context, tradeoffs, and careful validation. -## AI contributions +Human contributions may extend into core implementation, protocol behavior, trust boundaries, identity, transport, cryptography, and architecture when the change is well understood and properly justified. -AI-generated issues, reviews, and small PRs are explicitly welcome without prior assignment when they improve CLI behavior, logs, diagnostics, docs, skills, or integration accessibility. The merge bar for agent-facing changes is [#346](https://github.com/gosuda/portal-tunnel/issues/346). +Please follow `AGENTS.md` for implementation rules and the architecture and ADR documents for design decisions. -Every repeated agent instruction is a candidate accessibility bug. Fix the Portal surface and delete the instruction. Do not document another workaround. +## For AI Contributors -Agent usability alone is not a reason to change protocol, cryptography, trust, identity, transport, or architecture semantics. Core changes follow the same repository rules as human contributions. Generic feedback orchestration stays outside this repository ([#331](https://github.com/gosuda/portal-tunnel/issues/331)). \ No newline at end of file +AI contributions are strongly encouraged on the user-facing and integration surface of Portal. + +This includes CLI behavior, logs, diagnostics, documentation, skills, configuration ergonomics, installer and service integration, local harnesses, and other friction encountered while using Portal. + +Repeated instructions, parsing workarounds, ambiguous output, and integration-specific exceptions should be treated as signs that the Portal surface itself may need improvement. Prefer fixing the surface and removing the workaround. + +Core protocol semantics, cryptography, trust, identity, transport invariants, and architecture require careful human review. AI may identify problems or propose changes in these areas, but changes to the core should not be accepted solely on the basis of automated reasoning or agent usability. From 7a9e3cb0601bdd8acb4c2ec4e888b7af2c60ee54 Mon Sep 17 00:00:00 2001 From: gosunuts Date: Fri, 28 Aug 2026 16:52:30 +0900 Subject: [PATCH 5/5] docs: tighten AI contribution policy --- CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f38f0e898..dc98238d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -`AGENTS.md` is the core implementation guide. Architecture, product behavior, and design rationale belong in `docs/architecture.md` and `docs/adr/README.md`. This file is contribution policy. +`AGENTS.md` is the core implementation guide. This file is contribution policy. ## For Human Contributors @@ -10,7 +10,7 @@ Human review and judgment are especially important in the parts of the project w Human contributions may extend into core implementation, protocol behavior, trust boundaries, identity, transport, cryptography, and architecture when the change is well understood and properly justified. -Please follow `AGENTS.md` for implementation rules and the architecture and ADR documents for design decisions. +Please follow `AGENTS.md` for implementation rules. ## For AI Contributors @@ -18,6 +18,8 @@ AI contributions are strongly encouraged on the user-facing and integration surf This includes CLI behavior, logs, diagnostics, documentation, skills, configuration ergonomics, installer and service integration, local harnesses, and other friction encountered while using Portal. +AI contributors may file issues, reviews, and improvement proposals in these areas without prior assignment. + Repeated instructions, parsing workarounds, ambiguous output, and integration-specific exceptions should be treated as signs that the Portal surface itself may need improvement. Prefer fixing the surface and removing the workaround. Core protocol semantics, cryptography, trust, identity, transport invariants, and architecture require careful human review. AI may identify problems or propose changes in these areas, but changes to the core should not be accepted solely on the basis of automated reasoning or agent usability.