From 895bad9ac9cbe54f46cb6b945c17915fcbc7570b Mon Sep 17 00:00:00 2001
From: Sulkta <oss@sulkta.com>
Date: Sun, 28 Jun 2026 11:39:05 -0700
Subject: [PATCH] docs: public-facing README + contributing notes; generic CI
 comments

---
 .forgejo/workflows/gitleaks.yml | 16 ++++------------
 README.md                       | 16 ++++++++++++----
 aiken-escrow/README.md          |  2 +-
 3 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/.forgejo/workflows/gitleaks.yml b/.forgejo/workflows/gitleaks.yml
index 151fdfd..38df3b1 100644
--- a/.forgejo/workflows/gitleaks.yml
+++ b/.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
diff --git a/README.md b/README.md
index 2818b3e..7898581 100644
--- a/README.md
+++ b/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
 
diff --git a/aiken-escrow/README.md b/aiken-escrow/README.md
index 76c56d8..dc55f4c 100644
--- a/aiken-escrow/README.md
+++ b/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.