Polish repository presentation and community health docs

Author: jpKuji

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1,8 @@
 blank_issues_enabled: false
+contact_links:
+  - name: Documentation and setup help
+    url: https://github.com/Sense-Kit/sense-kit/blob/main/docs/README.md
+    about: Start here for the spec, runbooks, ADRs, and privacy notes before opening an issue.
+  - name: Security reporting
+    url: https://github.com/Sense-Kit/sense-kit/security/policy
+    about: Please report security and privacy issues privately through the security policy.

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

.github/pull_request_template.md

@@ -6,7 +6,15 @@ What changed?
 
 Why was this change needed?
 
-## Checks
+## Scope
+
+- [ ] Runtime logic
+- [ ] iOS UI
+- [ ] Contracts / schemas
+- [ ] Docs only
+- [ ] Tooling / CI
+
+## Validation
 
 - [ ] `pnpm build`
 - [ ] `pnpm test`
@@ -15,6 +23,12 @@ Why was this change needed?
 - [ ] `cd apps/ios/Packages/SenseKitUI && swift test`
 - [ ] `xcodebuild -workspace apps/ios/SenseKit.xcworkspace -scheme SenseKitApp -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO build`
 
+## Docs and architecture
+
+- [ ] README or docs updated if behavior changed
+- [ ] ADR added or updated if architecture changed
+- [ ] Background behavior claims are labeled as `VERIFIED_BY_PLATFORM_DOCS`, `REQUIRES_BENCH_TEST`, or `UNSAFE_TO_BUILD_AROUND`
+
 ## Risks
 
 Anything reviewers should watch closely?

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file.
 
+## Unreleased
+
+Documentation and repository polish:
+
+- rewrote the top-level README to present SenseKit more clearly as an open-source project
+- added a docs index for easier navigation
+- added security and support policies
+- improved GitHub issue and pull request guidance for contributors
+
 ## v0.1.0 - 2026-03-09
 
 First public scaffold release.

README.md

@@ -1,92 +1,93 @@
 # SenseKit
 
-SenseKit is an open-source context runtime for AI agents.
+[![CI](https://github.com/Sense-Kit/sense-kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Sense-Kit/sense-kit/actions/workflows/ci.yml)
 
-It runs on iPhone, listens to passive sensor signals, turns them into deterministic context events, and delivers those events to OpenClaw over signed HTTPS.
+SenseKit is an open-source iPhone context runtime for AI agents.
 
-The goal is simple: an AI agent should understand important real-world transitions without asking the user to build Shortcuts automations first.
+It listens to passive on-device signals like motion, location, workouts, power state, and lightweight calendar context, turns those signals into deterministic events, and delivers signed HTTPS payloads to OpenClaw.
 
-## Product thesis
+The project exists to solve one practical problem: an agent cannot act intelligently around the real world if the user has to build a pile of Shortcuts automations before anything works. SenseKit aims to be useful right after install and permission approval.
 
-SenseKit is:
+## Why SenseKit
 
-- passive-first
-- event-first
-- deterministic
-- local-first
-- OpenClaw-first
+- `Passive-first`: useful events should be possible without manual Shortcuts setup.
+- `Deterministic`: the runtime uses explicit rules, weights, and thresholds instead of opaque ML guesses.
+- `Local-first`: raw sensor data stays on the phone by default.
+- `Policy-aware`: each outbound event includes the safety context OpenClaw needs to react responsibly.
+- `OpenClaw-first`: the primary integration path is signed outbound delivery, not hosting a server on the phone.
 
-That means:
+## Current status
 
-- the iPhone app should do useful work right after install and permissions
-- event detection uses fixed weights and thresholds, not ML guesses
-- raw sensor data stays local by default
-- the main integration is an outbound webhook, not a phone-hosted server
+SenseKit is early, opinionated, and real.
 
-This repository is a monorepo. It keeps the iOS runtime, shared wire contracts, OpenClaw integration helpers, and project docs together because they change together.
+What already exists in this repository:
 
-## What data gets sent to OpenClaw
-
-SenseKit does not send a raw dump of everything your phone sees.
+- a deterministic corroboration engine for passive events
+- a Swift runtime package with Motion, Location, HealthKit, power, and calendar collectors
+- SQLite-backed runtime state, queueing, and audit logging
+- signed webhook delivery for OpenClaw
+- a SwiftUI app shell with onboarding, settings, audit log, and debug timeline scaffolding
+- a separate bench harness target for field testing
+- shared JSON schemas and TypeScript validation helpers
 
-What currently goes out:
+What is still being validated on real devices:
 
-- one event at a time, for example `motion_activity_observed` or `arrived_home`
-- the event time
-- a confidence score
-- short reasons like `motion.primary.walking` or `location.region_enter_home`
-- a small snapshot with coarse state like:
-  - place type: `home`, `work`, or `other`
-  - routine flags like `awake` or `workout`
-  - minimal calendar booleans
-  - battery bucket and charging state
-- a policy block that tells OpenClaw which response modes are safe
+- wake detection precision
+- driving detection precision
+- battery impact over normal daily use
+- background wake and delivery reliability
+- final onboarding polish
 
-What stays local by default:
+If you are evaluating the project, start with:
 
-- exact GPS coordinates
-- raw motion history
-- raw HealthKit values
-- calendar titles and attendees
-- local debug traces
-- tokens and secrets
+- [SPEC.md](SPEC.md)
+- [docs/README.md](docs/README.md)
+- [docs/bench/phase-1a-field-test.md](docs/bench/phase-1a-field-test.md)
+- [docs/runbooks/runtime-bootstrap.md](docs/runbooks/runtime-bootstrap.md)
 
-In the current bench app:
+## Architecture at a glance
 
-- Motion is currently forwarded as coarse activity events like `walking`, `running`, `stationary`, or `automotive`
-- Home / Work is currently forwarded as place events like `arrived_home`
+```mermaid
+flowchart LR
+    A["On-device collectors<br/>Motion, location, HealthKit,<br/>power, calendar"] --> B["Deterministic corroboration engine"]
+    B --> C["Context event<br/>confidence, reasons, policy"]
+    C --> D["Signed outbound queue"]
+    D --> E["OpenClaw webhook"]
+```
 
-So the phone sends structured context events, not a full sensor stream.
+SenseKit is a runtime, not a data exhaust pipeline. The phone keeps the raw sensor layer local and only sends small, structured events once the runtime is confident something meaningful happened.
 
-## What works today
+## What leaves the phone
 
-This repo already includes the first serious product scaffolding:
+SenseKit does not send a raw dump of everything the device sees.
 
-- a deterministic corroboration engine for passive events
-- a Swift runtime package with Motion, Location, HealthKit, power, and calendar collectors
-- SQLite-backed runtime state, queue, and audit log
-- signed webhook delivery for OpenClaw
-- a SwiftUI app shell with onboarding, settings, audit log, and debug timeline scaffolding
-- a separate bench harness target for field testing
-- shared JSON schemas and TypeScript validation helpers
+| Sent to OpenClaw | Stays local by default |
+| --- | --- |
+| One event at a time, such as `motion_activity_observed` or `arrived_home` | Exact GPS coordinates |
+| Event timestamp | Raw motion history |
+| Confidence score | Raw HealthKit values |
+| Short reason codes like `motion.primary.walking` | Calendar titles and attendees |
+| A small snapshot with coarse state | Local debug traces |
+| A policy block describing safe response modes | Tokens and secrets |
 
-What is not proven yet:
+In the current bench app, motion is forwarded as coarse activity events such as `walking`, `running`, `stationary`, or `automotive`, and place transitions are forwarded as events such as `arrived_home`.
 
-- real-device wake precision
-- real-device driving precision
-- battery impact over normal daily use
-- final onboarding polish
+## Repository guide
 
-In other words: the architecture and build system are in place, but the passive claims still need bench validation.
+- [`apps/ios`](apps/ios): the iPhone app, bench harness, runtime package, and SwiftUI package
+- [`packages/contracts`](packages/contracts): JSON schemas, fixtures, and TypeScript validation helpers
+- [`packages/openclaw-skill`](packages/openclaw-skill): example skill packaging for OpenClaw
+- [`packages/openclaw-plugin`](packages/openclaw-plugin): plugin surface for later OpenClaw integration work
+- [`packages/examples`](packages/examples): QR bootstrap and hook configuration examples
+- [`docs`](docs): ADRs, privacy notes, release notes, runbooks, and field-test plans
 
-## Repo layout
+Documentation entry points:
 
-- `apps/ios`: iPhone app, bench harness, Swift runtime package, and SwiftUI package
-- `packages/contracts`: JSON schemas, fixtures, and TypeScript validation helpers
-- `packages/openclaw-skill`: example skill packaging for OpenClaw
-- `packages/openclaw-plugin`: plugin surface for later OpenClaw integration work
-- `packages/examples`: webhook and QR bootstrap examples
-- `docs`: ADRs, privacy notes, bench plans, and runbooks
+- [docs/README.md](docs/README.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [SECURITY.md](SECURITY.md)
+- [SUPPORT.md](SUPPORT.md)
 
 ## Local setup
 
@@ -124,46 +125,30 @@ xcodebuild -workspace apps/ios/SenseKit.xcworkspace -scheme SenseKitApp -sdk iph
 xcodebuild -workspace apps/ios/SenseKit.xcworkspace -scheme SenseKitBenchApp -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO build
 ```
 
-## OpenClaw connectivity and security
+## OpenClaw connectivity
 
 For personal testing, keep OpenClaw private and use Tailscale instead of exposing the raw Gateway to the public internet.
 
-- Recommended first setup: OpenClaw stays on `gateway.bind: "loopback"` and is exposed privately with Tailscale Serve.
-- Do not expose the raw OpenClaw Gateway port publicly just to receive SenseKit hooks. The Gateway is a larger surface than one webhook path.
+- Keep OpenClaw on `gateway.bind: "loopback"` and expose it privately with Tailscale Serve.
 - Use a separate `hooks.token` for SenseKit hooks. Do not reuse `gateway.auth.token`.
-- Treat hook payloads as untrusted content even when they come from systems you control. Keep the receiving agent narrow and low-privilege.
-- A public hook-only reverse proxy or a small verifier relay can come later, but they are not the safest first deployment.
-- If OpenClaw returns `hook mapping failed`, remove any custom `transform` block first and test with the example mapping unchanged. SenseKit sends snake_case fields like `event.event_id`, `event.event_type`, and `snapshot.place.type`.
+- Treat hook payloads as untrusted content even when they come from systems you control.
+- If OpenClaw returns `hook mapping failed`, remove any custom `transform` block first and test with the example mapping unchanged.
 
-## Debug Timeline vs Audit Log
+## Contribution focus
 
-- `Debug Timeline` is the local notebook. It shows what the phone sensed and what the local runtime did with it.
-- `Audit Log` is the delivery ledger. It shows whether a finished outbound event was queued, delivered, failed, or expired on the way to OpenClaw.
-
-That means:
-
-- use `Debug Timeline` when you want to debug Motion, Location, Settings, or rule evaluation
-- use `Audit Log` when you want to know whether OpenClaw actually received the event
-
-Location events are included in Audit once they become real outbound events. For example, `arrived_home` should show up there after it is queued and delivered.
-
-## First development focus
-
-If you want to help on the MVP, the highest-value work is:
+The highest-value work for the current milestone is:
 
 1. passive wake validation on real devices
 2. driving detection validation on real commutes
 3. background wake and delivery reliability
 4. onboarding and debug timeline polish
 
-The best starting docs are:
-
-- `docs/adr`
-- `docs/bench/phase-1a-field-test.md`
-- `docs/runbooks/runtime-bootstrap.md`
+Contributions are welcome. If your change affects architecture, add or update an ADR in [`docs/adr`](docs/adr).
 
-## Open source notes
+## Project standards
 
 - License: Apache-2.0
-- Contributions are welcome. See `CONTRIBUTING.md`
-- Architecture decisions live in `docs/adr`
+- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- Security policy: [SECURITY.md](SECURITY.md)
+- Support guide: [SUPPORT.md](SUPPORT.md)

SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Supported versions
+
+SenseKit is still early-stage software. Security fixes are currently tracked against:
+
+- the latest commit on `main`
+- the latest tagged release
+
+Older snapshots may receive fixes on a best-effort basis, but only the current development line should be treated as supported.
+
+## Reporting a vulnerability
+
+Please do not open public GitHub issues for security reports.
+
+Send reports to `julian@sensekit.ai` with:
+
+- a short description of the issue
+- the affected component or file
+- impact if you know it
+- clear reproduction steps or a proof of concept if you have one
+
+If the report is valid, the goal is to acknowledge it within 3 business days and keep you updated until a fix or mitigation is available.
+
+## Scope and expectations
+
+The most sensitive areas in this repository are:
+
+- webhook signing and verification paths
+- token handling and configuration surfaces
+- anything that could accidentally widen what leaves the device
+- local data storage and debug export behavior
+
+Please report suspected privacy leaks the same way you would report a security bug.

SUPPORT.md

@@ -0,0 +1,21 @@
+# Support
+
+Use the path that matches what you need:
+
+- Bug reports: open a GitHub issue with the bug template
+- Feature requests: open a GitHub issue with the feature template
+- Security or privacy issues: follow [SECURITY.md](SECURITY.md) and report them privately
+- Setup, architecture, or documentation questions: start with [docs/README.md](docs/README.md) and then open an issue if the answer is still missing
+
+When you open an issue, include enough context to make it actionable:
+
+- the area you are working in
+- your device or environment
+- the exact behavior you expected
+- what you already tried
+
+For background behavior claims, please say whether the claim is:
+
+- `VERIFIED_BY_PLATFORM_DOCS`
+- `REQUIRES_BENCH_TEST`
+- `UNSAFE_TO_BUILD_AROUND`

docs/README.md

@@ -0,0 +1,38 @@
+# SenseKit Documentation
+
+This folder holds the working documentation for SenseKit.
+
+If you are new to the project, use this reading order:
+
+1. [README.md](../README.md) for the high-level product and repo overview
+2. [SPEC.md](../SPEC.md) for the product spec and event model
+3. [docs/runbooks/runtime-bootstrap.md](runbooks/runtime-bootstrap.md) for the current integration and runtime bootstrap path
+4. [docs/bench/phase-1a-field-test.md](bench/phase-1a-field-test.md) for real-device validation work
+5. [docs/adr](adr) for the architecture rules that shape implementation decisions
+
+## By topic
+
+- [Architecture Decision Records](adr)
+  - why the project is passive-first
+  - why event detection is deterministic
+  - why delivery is outbound-only
+  - what platform constraints the project treats as real
+- [Bench and validation docs](bench)
+  - field-test plans
+  - evidence for background behavior claims
+- [Runbooks](runbooks)
+  - runtime bootstrap and integration setup
+- [Privacy docs](privacy)
+  - minimization rules
+  - privacy policy
+- [Release notes](releases)
+  - release snapshots and beta notes
+
+## Recommended paths
+
+Use these if you already know why you are here:
+
+- Evaluating the project: [SPEC.md](../SPEC.md), [docs/adr](adr), [docs/bench/phase-1a-field-test.md](bench/phase-1a-field-test.md)
+- Integrating with OpenClaw: [docs/runbooks/runtime-bootstrap.md](runbooks/runtime-bootstrap.md)
+- Reviewing privacy and data handling: [docs/privacy/minimization.md](privacy/minimization.md), [docs/privacy/privacy-policy.md](privacy/privacy-policy.md)
+- Contributing code or docs: [CONTRIBUTING.md](../CONTRIBUTING.md), [CHANGELOG.md](../CHANGELOG.md)