docs: public-facing README + contributing notes; generic CI comments

.forgejo/workflows/gitleaks.yml

@@ -1,16 +1,9 @@
 # .forgejo/workflows/gitleaks.yml
 #
-# Sulkta canonical gitleaks workflow. Drop a copy into every public repo at
-# `.forgejo/workflows/gitleaks.yml` after the Forgejo act_runner is registered
-# (task #295).
-#
-# Pairs with the pre-receive hook installed on every bare repo — that one is
-# the strict enforcement layer (rejects the push); this one provides the
-# per-PR red ✗ that branch-protection rules can require before merge.
-#
-# Layer 1 (this workflow): visible per-PR status, can be a required check.
-# Layer 2 (pre-receive hook): strict enforcement at the server.
-# Layer 3 (the CI host cron sweep): nightly full-history sweep across all repos.
+# Scans the repository for committed secrets with gitleaks on every push and
+# pull request. Use it as a required status check via branch protection so a
+# leaking change cannot be merged. Works the same on GitHub Actions if you
+# move the file to `.github/workflows/`.
 
 name: gitleaks
 
@@ -38,4 +31,3 @@ jobs:
       - name: scan
         run: |
           ./gitleaks detect --source . --no-banner --redact --verbose
-# re-run smoke 2026-05-28

README.md

@@ -140,13 +140,21 @@ derived-key scope.
 
 Wallet + governance paths exercised on **mainnet**. DAO + escrow
 paths exercised end-to-end on **preprod**; the escrow validator has
-undergone internal review (`audits/`) but **no third-party audit**.
-Treat the escrow flows as use-at-own-risk until external review lands
-— see `aiken-escrow/README.md` for the WIP threat model.
+had a code review but **no third-party security audit**. Treat the
+escrow flows as use-at-own-risk until external review lands — see
+`aiken-escrow/README.md` for the WIP threat model.
+
+## Contributing
+
+Issues and pull requests are welcome. Before opening a PR, run
+`cargo fmt`, `cargo clippy --all-targets`, and `cargo test`. Changes
+that touch the on-chain validator (`aiken-escrow/`) or the signing
+path (`aldabra-core`) should spell out the security reasoning in the
+PR description.
 
 ## License
 
-See `LICENSE`.
+See [`LICENSE`](LICENSE).
 
 ## Dependencies of note
 

aiken-escrow/README.md

@@ -61,5 +61,5 @@ These are KNOWN gaps the validator does not protect against:
   agree / veto / settle / refund-timeout) implemented + unit-tested.
 - MCP tool wrappers exposed under `escrow_*` prefix.
 - Lifecycle paths exercised end-to-end on preprod (settle / veto /
-  refund-timeout) — findings in `audits/`.
+  refund-timeout).
 - **Outstanding:** external third-party audit before mainnet release.