Settle the repo for public GitHub release

Bundle landing the project on github.com/hubzero/botshield:
README front page (logo banner + tagline + badges, header
cleaned up); GitHub-conventional meta files (SECURITY.md,
CONTRIBUTING.md, Dependabot); CI shape for public Actions runs
(docroot traversal, fixture restore, a2enmod rewrite, fail-
secrets, paths-ignore for docs-only changes); BS_REPO fallback
hardened to a clear error.

Author: nkissebe

.github/dependabot.yml

@@ -0,0 +1,36 @@
+# Auto-PR dependency updates for the bits of this repo that pin
+# external versions. The C module itself has no package manifest —
+# it links against system Apache + OpenSSL + libcurl + json-c which
+# distros track, so there's nothing for Dependabot to check there.
+#
+# Schedule is weekly (Monday) so PRs land in batches instead of
+# trickling. Open-pull-request limit keeps things manageable.
+
+version: 2
+updates:
+  # GitHub Actions used by .github/workflows/ci.yml — actions/checkout,
+  # actions/setup-python, actions/cache, actions/upload-artifact.
+  # CI's deprecation warnings (Node.js 20 -> 24) will land here as
+  # an update PR when GitHub publishes new majors.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+
+  # Pytest framework + Playwright + Hypothesis + report tooling.
+  - package-ecosystem: "pip"
+    directory: "/tests"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+
+  # Docs renderer (markdown-it-py).
+  - package-ecosystem: "pip"
+    directory: "/tools"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 3

.github/workflows/ci.yml

@@ -13,14 +13,32 @@ name: CI
 # or after a parser change.
 
 on:
+  # Skip pushes/PRs that only touch docs — repeated `make docs`
+  # iterations or markdown tweaks shouldn't burn a runner. CI still
+  # fires the moment a code/test/config file is in the diff
+  # alongside the docs change. workflow_dispatch is always
+  # available for manual override.
   pull_request:
     branches: [ main ]
+    paths-ignore:
+      - 'docs/**'
+      - 'docs-src/**'
+      - 'site-src/**'
+      - '**/*.md'
+      - 'LICENSE'
   push:
     branches: [ main ]
+    paths-ignore:
+      - 'docs/**'
+      - 'docs-src/**'
+      - 'site-src/**'
+      - '**/*.md'
+      - 'LICENSE'
   # Manual trigger only — used to fire the 8h soak and the fuzz
   # campaigns (each can spend hours of runner time, so we don't run
-  # them on a cron). Hit the "Run workflow" button in GitHub Actions
-  # to invoke.
+  # them on a cron). Also lets you re-run the whole CI on a docs-only
+  # commit when you're done iterating and want one final check. Hit
+  # the "Run workflow" button in GitHub Actions to invoke.
   workflow_dispatch:
 
 env:

CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to mod_botshield
+
+Thanks for your interest. The project is small and the workflow is
+deliberately low-ceremony.
+
+## Quick start
+
+```sh
+git clone https://github.com/hubzero/botshield.git
+cd botshield
+sudo tests/setup/provision.sh
+tests/run --parallel --mark "not browser"
+```
+
+`provision.sh` is idempotent; it installs apt packages, builds and
+installs the module, sets up a self-signed-cert HTTPS dev vhost on
+`localhost`, generates per-provider dummy captcha secrets, and
+creates the test venv at `tests/.venv/`. Re-run it any time you
+want to reset the environment.
+
+After that, `tests/run` is the dispatcher — flags + markers are
+documented in [`tests/README.md`](tests/README.md).
+
+## Reporting bugs and asking questions
+
+- **Bugs**: open a GitHub issue with reproduction steps. A minimal
+  Apache config snippet plus a `curl` invocation that triggers the
+  problem is the gold standard.
+- **Security bugs**: do not open public issues. See
+  [SECURITY.md](SECURITY.md).
+- **Questions / feature ideas**: GitHub Discussions is fine for
+  open-ended things; issues are fine for things you want tracked.
+
+## Submitting a pull request
+
+1. Fork → branch from `main`.
+2. Make the change. Keep it focused — one concern per PR is
+   easier to review than three concerns bundled.
+3. **Run the test suite**:
+   ```sh
+   tests/run --parallel
+   ```
+   PRs are gated on CI. Locally-green tests + clean CI is the
+   baseline; flake-on-CI-only happens occasionally and is a
+   conversation, not an automatic block.
+4. **Rebuild the docs** if you touched `docs-src/*.md` or
+   `site-src/*`:
+   ```sh
+   make docs
+   git add docs/
+   ```
+   The CI `docs-fresh` job will fail your PR if you forget.
+5. **Commit messages**: imperative, focused on the *why* when it
+   isn't obvious from the diff. The git log shows the style; copy
+   what you see. No "fix typo" PRs are too small to be welcome.
+6. **Open the PR**. Describe what changed and what you tested.
+   Screenshots / log excerpts when relevant.
+
+## Where things live
+
+- `src/` — the C source. 19 modules, each `.c` paired with `.h`.
+  `DESIGN.md` explains the module split.
+- `apache/botshield-dev.conf` — the dev vhost. Path-templated
+  through `${BS_REPO}` so it works on any developer's checkout.
+- `docs-src/` — markdown source for the operator handbook
+  (rendered to `docs/` by `make docs`).
+- `tests/pytests/` — pytest cases. Reusable framework helpers
+  in `tests/botshield_test/`.
+- `tests/fuzz/` — LibFuzzer harnesses for the cookie + robots
+  parsers.
+- `tests/bench/` — wrk + oha benchmark scripts.
+- `tools/` — `build_site.py` (docs renderer) +
+  `refresh-bot-ranges.sh` (operator cron tool).
+
+`CHANGELOG.md` is date-organized and gets an entry per
+notable PR. `DESIGN.md` is current-state architecture; update it
+when you change behavior, not just when you ship a feature.
+
+## Code style
+
+- C99. Apache style for indentation (4 spaces, no tabs except
+  Makefile). `.editorconfig` enforces the basics.
+- Function/symbol prefixes: `bs_` / `BS_` for cross-file public
+  symbols. File-local helpers use `static` and don't need the
+  prefix.
+- Comments explain *why* something is the way it is when the
+  code itself can't say it. Don't narrate what `if (x > 0)` does;
+  do explain why we picked `x > 0` over `x >= 0`.
+- No regex on the hot path — hand-rolled byte scanners
+  (`memcmp` / `memchr`). Reserve regex for config-time.
+
+## License
+
+By contributing, you agree your contribution is licensed under the
+MIT License (see [LICENSE](LICENSE)).