docs: welcome issue-led PRs and Markdown proposals

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -9,8 +9,8 @@ body:
         Thanks for taking the time to report a bug. Please fill in the
         details below so the community can reproduce and evaluate it.
 
-        If you want to contribute a code fix, start with this report and wait
-        for a maintainer to confirm the scope before opening the pull request.
+        PRs are welcome. Prefer linking a fix to this report and include
+        test steps and results. See [CONTRIBUTING.md](https://github.com/srcfl/ftw/blob/master/CONTRIBUTING.md).
 
         FTW Community has no guaranteed response or resolution time. Do not
         include credentials, access tokens, private keys, or unredacted
@@ -77,10 +77,3 @@ body:
     attributes:
       label: Anything else?
       description: Config snippets, screenshots, network topology, etc.
-  - type: checkboxes
-    id: text-first
-    attributes:
-      label: Contribution path
-      options:
-        - label: I understand that Sourceful handles implementation and external contributions use issues, not pull requests.
-          required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -10,9 +10,9 @@ body:
         a thread in [Discussions](../../discussions) first — issues are
         best for concrete, actionable proposals.
 
-        Sourceful develops FTW. External users submit issues with needs and
-        evidence; we do not accept external pull requests, including docs and
-        drivers. You do not need to design an API or write code to make a request.
+        PRs are welcome, preferably based on an issue. A broad idea can also
+        start as a short Markdown PR; a concrete fix should include test evidence.
+        You do not need to design an API or write code to make a request.
   - type: textarea
     id: problem
     attributes:
@@ -64,10 +64,3 @@ body:
     attributes:
       label: Anything else?
       description: Hardware datasheets, protocol docs, screenshots, links.
-  - type: checkboxes
-    id: text-first
-    attributes:
-      label: Contribution path
-      options:
-        - label: I understand that Sourceful handles implementation and external contributions use issues, not pull requests.
-          required: true

.github/check-no-planning-docs.sh

@@ -1,14 +1,9 @@
 #!/usr/bin/env bash
 # Fails when a change adds agent planning artefacts to the repository.
 #
-# Plans, design specs and task breakdowns describe how work was going to be
-# done. They are stale the moment the work lands, nobody reads them again,
-# and they bury the docs that operators actually need. One PR carried 2,200
-# lines of them; the author's own point was that this would never have
-# happened if the repo had simply said so. So the repo says so, here.
-#
-# Put the reasoning in the PR description instead. It gets read while the
-# change is being reviewed, and then it is archived rather than maintained.
+# Short Markdown proposals are welcome in the PR description or relevant
+# maintained docs. This check rejects known scratch paths and dated agent
+# work plans, not proposals as a contribution type. See CONTRIBUTING.md.
 set -euo pipefail
 
 BASE_SHA="${PLANNING_DOCS_BASE_SHA:-}"
@@ -41,12 +36,12 @@ if [ -n "${offenders}" ]; then
   echo "This change adds agent planning documents:" >&2
   echo "${offenders}" >&2
   cat >&2 <<'MSG'
-Plans, specs and design notes do not belong in the repository — see the
-"Working alongside other people" section in AGENTS.md. Move the reasoning
-into the pull request description and drop the files.
+Task breakdowns and agent scratch notes do not belong in the repository.
+Move work reasoning into the PR description and drop these files.
 
-Documentation that explains architecture, a safety invariant, or a step an
-operator has to take is welcome under docs/ and is not what this checks for.
+Short Markdown proposals are welcome in the PR description or relevant
+maintained docs. Mark proposed behaviour as proposed. Architecture, safety
+and operator docs remain welcome. See CONTRIBUTING.md and AGENTS.md.
 MSG
   exit 1
 fi

.github/pull_request_template.md

@@ -1,7 +1,9 @@
 <!--
-Sourceful maintains implementation PRs. External users: please open an issue
-for bugs, needs and evidence instead, including documentation and driver work.
-See CONTRIBUTING.md. Acceptance of an issue does not invite an external PR.
+External PRs are welcome, preferably based on an issue. Broad proposals may
+be short Markdown PRs; concrete fixes should include relevant test evidence.
+Make scope and results clear for people and agents. See CONTRIBUTING.md.
+For a proposal, mark runtime-only checks as not applicable and state what
+evidence the implementation will need.
 -->
 
 ## Problem and result
@@ -14,7 +16,9 @@ See CONTRIBUTING.md. Acceptance of an issue does not invite an external PR.
 
 ## Verification
 
-<!-- Give the tests, runs, hardware evidence or rendered views that support the result. -->
+<!-- Give reproducible test steps and actual results. For device behaviour,
+include model, firmware and hardware evidence; keep missing HW checks explicit
+and the PR as a proposal/draft until complete. Separate simulations from HW. -->
 
 ## Checklist
 

AGENTS.md

@@ -7,8 +7,10 @@ requirements and [docs/roadmap.md](docs/roadmap.md) for acceptance evidence.
 These are direction, not claims that all planned behaviour has shipped.
 
 Fredrik owns FTW's direction. Sourceful develops and maintains it. External
-users submit issues; we do not accept external pull requests, including docs
-and drivers. See [CONTRIBUTING.md](CONTRIBUTING.md).
+PRs are welcome, preferably based on issues. Broad proposals may start as
+short Markdown PRs; concrete fixes need relevant test evidence. Work is
+agentic first: make the problem, scope and results clear enough for people
+and agents to assess and continue. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Product rules
 
@@ -129,10 +131,12 @@ landed on somebody else's finished work.
   enough.
 
 Keep VISION.md and the roadmap current as the maintained product direction.
-Task plans, design drafts, breakdowns and agent scratch notes stay out of the
-repository; [`.github/check-no-planning-docs.sh`](.github/check-no-planning-docs.sh) enforces
-this. Commit the change, its tests and a changeset; put the reasoning in the
-PR description, where it is read during review and then archived.
+Short Markdown proposals may update the relevant maintained docs or use the
+PR description. Mark proposed behaviour as proposed until it ships. Keep task
+breakdowns, run logs and agent scratch notes out of the repository;
+[`.github/check-no-planning-docs.sh`](.github/check-no-planning-docs.sh) checks known
+scratch paths. Code PRs include the change, relevant tests and a changeset
+when required. Put work reasoning in the PR description.
 
 ## Build and test
 

APPROVAL_POLICY.md

@@ -23,4 +23,6 @@ that check. Preserve the owner's release and beta-review rules in AGENTS.md.
 
 This policy grants no extra authority to approve, merge, release or operate a
 site. It also adds no confirmation requirement when the owner has already
-authorized the action. External users submit issues; Sourceful maintains PRs.
+authorized the action. External PRs are welcome under CONTRIBUTING.md;
+Sourceful reviews and maintains changes. Submission grants no merge or
+release authority, whether a person or an agent wrote the change.

CONTRIBUTING.md

@@ -1,22 +1,41 @@
 # Contributing to FTW
 
-Sourceful develops FTW and Fredrik owns its direction. External users help
-through [issues](https://github.com/srcfl/ftw/issues): report bugs, describe
-needs and share evidence. We do not accept external pull requests, including
-documentation, driver and website changes. Acceptance of an issue does not
-invite an external implementation PR.
-
-The [product vision](VISION.md) guides the work Sourceful selects. Users may
-still run, inspect and adapt FTW under its existing license. This policy does
-not change the license or past contributions. The development and sign-off
-instructions below apply to Sourceful-maintained changes and local work.
+Sourceful develops and maintains FTW; Fredrik owns its direction. External
+PRs are welcome, including code, drivers, documentation and website changes.
+Prefer an [issue](https://github.com/srcfl/ftw/issues) that states the need and
+evidence, and link it from the PR. Small fixes do not need a separate issue.
+The [product vision](VISION.md) guides scope and priority.
+
+For a broad product or architecture idea, a short Markdown PR is a useful
+start. Explain the problem, proposed result and how we could test it in the
+PR description or relevant maintained docs. Mark proposals as proposed;
+keep agent scratch notes and task breakdowns out of the repository. Concrete
+fixes can include code and tests. No proposal promises a delivery date.
+
+## Agentic first
+
+People and agents should be able to assess and continue the work from its
+record. State the problem, scope, relevant issue, test steps and results.
+Use focused changes and reproducible evidence. The submitter checks agent
+output and remains responsible for the contribution and its sign-off.
+
+Test evidence should fit the change. For device behaviour, include hardware
+model, firmware, test steps and observed results before merge. State missing
+hardware tests and keep the PR as a proposal or draft until they are done.
+Simulator tests help catch bugs but do not prove physical support. Docs do
+not need hardware tests; UI changes need a browser review. Driver control
+keeps its separate safety and hardware acceptance gates.
+
+This policy changes no license, past attribution or release authority.
 
 ## Website
 
 The public website (<https://ftw.energy>) lives in its own
 repository, [`srcfl/ftw-web`](https://github.com/srcfl/ftw-web). Landing-page
-copy, install instructions and other site content live there. Report website
-changes in [its issue tracker](https://github.com/srcfl/ftw-web/issues).
+copy, install instructions and other site content live there. Use
+[its issue tracker](https://github.com/srcfl/ftw-web/issues) and PRs for website
+changes. Shared Lua drivers belong in
+[`srcfl/device-drivers`](https://github.com/srcfl/device-drivers).
 
 ## License of contributions
 
@@ -89,11 +108,11 @@ involved. Add relevant logs, screenshots or protocol documents when available.
 Do not post credentials or private site data. You do not need to design an API
 or write a patch to report a problem.
 
-Sourceful decides scope and priority and links implementation PRs to the issue.
-External PRs are not the intake path; maintainers may close them and direct the
-author to issues. General questions can still use Discussions or Discord.
+Fredrik sets direction and priority; Sourceful reviews and maintains changes.
+Link related issues and PRs so the evidence stays easy to follow. General
+questions can use Discussions or Discord.
 
-## Sourceful pull requests
+## Pull requests
 
 - State the household need, selected scope and relevant issue or owner request.
 - Keep the change focused and coordinate overlap with open work.

README.md

@@ -25,9 +25,9 @@ while keeping expert controls and Lua drivers available.
 [docs/roadmap.md](docs/roadmap.md) lists the outcomes and proof needed. These
 include goals that have not shipped; the capability list below is separate.
 
-Sourceful Energy maintains FTW Community under Apache-2.0. External users
-report bugs, needs and evidence through [issues](https://github.com/srcfl/ftw/issues).
-We do not accept external pull requests, including documentation and drivers.
+Sourceful Energy maintains FTW Community under Apache-2.0. Contributions are
+welcome, preferably starting with [issues](https://github.com/srcfl/ftw/issues).
+Share a short Markdown proposal or a focused fix with relevant test evidence.
 See [CONTRIBUTING.md](CONTRIBUTING.md). Community help is best effort;
 [SUPPORT.md](SUPPORT.md) describes separate commercial services.
 

SUPPORT.md

@@ -17,9 +17,9 @@ Use the public community channels for help:
   searchable questions, ideas, and open-ended technical conversation;
 - report reproducible bugs and request features in
   [GitHub Issues](https://github.com/srcfl/ftw/issues);
-- describe proposed fixes, driver needs, test evidence and documentation
-  corrections in issues. Sourceful implements selected changes; external pull
-  requests are not accepted. See [CONTRIBUTING.md](CONTRIBUTING.md).
+- share proposed fixes, driver needs and test evidence in issues. PRs are
+  welcome, including short Markdown proposals and documentation fixes.
+  See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 Maintainers and community members may help on a best-effort basis. A question
 may receive no response, and a fix may not arrive on a particular schedule.

VISION.md

@@ -205,11 +205,18 @@ Agents work within the scope and authority given to them. Reviews should
 provide an independent assessment and evidence; file-based reviewer lists
 do not define product ownership.
 
-External users contribute through issues: bugs, needs, hardware evidence and
-suggestions. FTW does not accept external pull requests, including drivers,
-documentation and website changes. Sourceful maintains implementation PRs.
-Users may still inspect, run and adapt the software under its existing license.
-This contribution policy changes no license or copyright attribution.
+External contributions are welcome, including code, drivers, documentation
+and website PRs. Prefer an issue that states the need and evidence. A broad
+product or architecture proposal can start as a short Markdown PR; a concrete
+fix can include code and tests. Hardware changes need relevant hardware
+evidence before we claim working support.
+
+Development is agentic first. Make problems, scope, test steps and results
+clear enough for people and agents to assess and continue the work. The
+submitter checks the result; agent output alone is not test evidence.
+Sourceful reviews and maintains changes; Fredrik sets direction and priority.
+An accepted issue or proposal does not promise implementation or delivery.
+This policy changes no license, copyright attribution or release authority.
 
 The operating rules live in [AGENTS.md](AGENTS.md), review routing in
 [APPROVAL_POLICY.md](APPROVAL_POLICY.md), and contribution details in

docs/roadmap.md

@@ -196,8 +196,12 @@ telemetry-only driver or require every house to supply a thermal model.
 
 ## How work enters the roadmap
 
-External users submit issues, not PRs. Sourceful implements selected work.
-Acceptance of an issue does not invite an external implementation PR.
+Contributions are welcome, preferably based on an issue. Broad ideas may
+start as short Markdown PRs; concrete fixes can include code and relevant
+test evidence. Hardware claims need hardware results. Work is agentic first:
+make the problem, scope and results clear enough for people and agents to
+assess and continue. Fredrik sets priority; Sourceful reviews and maintains
+changes. An accepted issue or proposal does not promise delivery.
 
 For each selected change, state the household need, the behaviour to change,
 the existing work it touches and the evidence that will establish completion.