forkit-ai-footprints 0.2.1 → 0.2.5

package/PRIVACY.md

@@ -59,10 +59,13 @@ AI Footprints may call HTTP(S) endpoints only when the hostname is one of:
 - `localhost`
 - `127.0.0.1`
 - `::1`
+- `www.forkit.dev`, limited to `/api/v1/ai-footprints/challenges` and
+  `/api/v1/ai-footprints/contributions` after explicit Preview consent and the
+  one-hour eligibility gate.
 
-Remote endpoints and endpoints containing embedded credentials are rejected.
+Other remote endpoints and endpoints containing embedded credentials are rejected.
 AI Footprints contains no Forkit.dev login, registry-write, passport-publish,
-Runtime_C2-write, billing, telemetry-upload, or deployment client.
+Runtime_C2-write, billing, general telemetry, or deployment client.
 
 `forkit-ai-footprints serve` binds only to `127.0.0.1`. Its rescan route
 requires the same page origin and a random in-memory session token. The route
@@ -95,11 +98,11 @@ generate one App Attest key and store only its opaque key identifier in the
 device-only Keychain. The current UI and CLI do not invoke enrollment,
 attestation, assertion generation, or upload.
 
-On first launch, the native app asks whether aggregate measurements may be
-prepared for global comparison. The answer is stored locally in macOS user
-defaults as two booleans (asked and allowed). It is not a device identifier and
-is never transmitted. A user who chose “Not now” can reopen the same permission
-from the comparison view.
+On first launch of the v2 Preview consent, the native app states that an
+anonymous aggregate will be sent after one valid observed hour and refreshed
+when internet is available. The answer and consent version are stored locally
+in macOS user defaults. A user who chose “Not now” can reopen the same
+permission from the comparison view. No request is made before permission.
 
 ## Filesystem identity
 
@@ -140,19 +143,20 @@ used as automatic evidence of ownership, safety, provenance, or passport status.
 
 ## Anonymous contribution boundary
 
-The local app can create an allowlisted schema `2.0` preview only after at least
-3,600 valid observed seconds. First-launch permission and exact payload review are
-separate actions. The preview
+The local app can create and send an allowlisted schema `2.0` Preview only after
+at least 3,600 valid observed seconds and explicit v2 native permission. The Preview
 contains valid seconds, AI-active seconds, activity ratio, supported app count
 and categories, model/loaded/runtime counts, recognized model-file bytes,
 macOS major, architecture, and scanner/runtime schema versions. It excludes
 names, process counts, CPU/RAM values, guess, device identity, local scan ID,
-timestamps, and all item-level records. The CLI and app still have no uploader. A
-separate Forkit.dev aggregate endpoint candidate exists with contribution writes
-disabled by default. That candidate now fails closed without Apple App Attest
-verification and excludes quarantined or revoked installations from the public
-pulse. The CLI still contains no proof enrollment or upload transport. Enabling
-either remains a founder/security release gate.
+timestamps, and all item-level records. The native app generates one owner-only
+local Ed25519 key, signs the exact aggregate against a one-time server challenge,
+and stores a small local sync receipt. The server persists only a keyed hash of
+the public contribution identity and one latest aggregate. Community Preview
+signatures prevent undetected payload changes and simple replay; they do not
+prove unique hardware or truthful measurement. Public Preview copy must say
+community-reported and not hardware-verified. Apple App Attest verification and
+verified ranking remain a separate founder/security release gate.
 
 ## Local share page
 

package/README.md

@@ -1,8 +1,17 @@
 # Forkit AI Footprints
 
-Forkit AI Footprints is a private, metadata-only view of the models, runtimes,
-and AI agents present on a Mac. The prepared package and command are
-`forkit-ai-footprints`.
+[![CI](https://github.com/arpitasarker01/forkit-ai-footprints/actions/workflows/ci.yml/badge.svg)](https://github.com/arpitasarker01/forkit-ai-footprints/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/forkit-ai-footprints)](https://www.npmjs.com/package/forkit-ai-footprints)
+[![License: MIT](https://img.shields.io/badge/License-MIT-2f2361.svg)](./LICENSE)
+
+Forkit AI Footprints is an open-source, private-by-default, metadata-only view
+of the models, runtimes, and AI agents present on a device. The public package
+and command are `forkit-ai-footprints`.
+
+[Product page](https://www.forkit.dev/ai-footprint) ·
+[npm](https://www.npmjs.com/package/forkit-ai-footprints) ·
+[Releases](https://github.com/arpitasarker01/forkit-ai-footprints/releases) ·
+[Contributing](./CONTRIBUTING.md) · [Security](./SECURITY.md)
 
 It is derived from the discovery lessons in Forkit Connect, but it has a
 different safety boundary: AI Footprints does not authenticate to Forkit.dev and has
@@ -58,7 +67,7 @@ git clone https://github.com/arpitasarker01/forkit-ai-footprints.git
 cd forkit-ai-footprints
 npm ci
 npm pack
-npm install -g ./forkit-ai-footprints-0.2.1.tgz
+npm install -g ./forkit-ai-footprints-0.2.5.tgz
 forkit-ai-footprints serve
 ```
 
@@ -186,10 +195,36 @@ forkit-ai-footprints scan --no-mcp
 
 CLI flags cannot bypass the required monitoring session. The local UI enables
 an exact schema `2.0` aggregate preview only after 3,600 valid observed seconds;
-the installed app asks once on first launch whether aggregate comparison is
-allowed, and no upload transport exists. The
-payload excludes app/model names, process counts, CPU/RAM, chat, workspace,
-repository, device, guess, local scan, and account identifiers.
+the installed app asks with versioned consent whether the anonymous aggregate
+may join the Global AI Preview. When allowed, the app sends one latest signed
+aggregate after the one-hour eligibility gate and refreshes that same row when
+new valid observation time is available. The server does not count refreshes as
+new installations. The payload excludes app/model names, process counts,
+CPU/RAM, chat, workspace, repository, device, guess, local scan, and account
+identifiers.
+
+### How the community Preview is calculated
+
+- A **contributing installation** is an opted-in local installation that has
+  reached at least 3,600 valid observed seconds and successfully submitted a
+  signed aggregate. Installing or downloading the package alone does not count.
+- Repeated syncs use the same private local contribution key and replace that
+  installation's previous aggregate. They do not increase the participant
+  total.
+- The global AI-active rate is duration-weighted:
+  `sum(AI-active seconds) / sum(valid observed seconds)` across eligible latest
+  rows. A long observation therefore contributes proportionally more evidence
+  than a short observation.
+- npm downloads are reported separately as registry download events. They are
+  not unique people, devices, installations, or consenting participants.
+- Percentile placement stays unavailable until at least 30 eligible
+  installations. Regional output stays hidden until its privacy threshold is
+  met.
+
+The service evaluates Preview eligibility once a minute. Network submissions
+are locally throttled and retried when internet is available; this is not a
+promise to upload once every 60 minutes. See [the privacy boundary](./PRIVACY.md)
+for the exact allowlist and exclusions.
 
 ## Shared core API
 
@@ -293,6 +328,18 @@ Storage, runtime-freshness, resource-attribution, and Developer ID truth
 boundaries are defined in
 [`docs/MACOS_MEASUREMENT_FOUNDATION.md`](./docs/MACOS_MEASUREMENT_FOUNDATION.md).
 
+## Contributing and security
+
+Forkit AI Footprints is an MIT-licensed open-source client. Bug reports, focused
+feature proposals, tests, accessibility and localization improvements, and
+privacy-preserving detector fixes are welcome through GitHub issues and pull
+requests. Maintainers review every accepted change; pull requests cannot publish
+an npm release automatically.
+
+Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a pull request. Report
+security or privacy vulnerabilities privately through the repository Security
+tab as described in [`SECURITY.md`](./SECURITY.md), never in a public issue.
+
 ## Accuracy boundary
 
 AI Footprints has no defensible global accuracy percentage yet. Runtime API evidence is

package/STATUS.md

@@ -1,12 +1,12 @@
 # Forkit AI Footprints Status
 
-Last updated: 2026-08-27
+Last updated: 2026-08-29
 
-Version: `0.2.1`
+Version: `0.2.5`
 
 Production classification: `current` for Apple Silicon macOS
 
-Release state: local v0.2.1 npm-first release candidate. The npm
+Release state: v0.2.5 npm-first community Preview is public. The npm
 bootstrap installs a persistent unsigned local app; Developer ID signing and
 notarization remain future work.
 
@@ -33,9 +33,15 @@ notarization remain future work.
   width instead of staying at tiny fixed pixel sizes.
 - Explicit Start/Stop Monitoring with repeated one-second macOS process-tree
   sampling, cumulative CPU-time deltas, two-sample entry and three-sample exit
-  hysteresis, and sleep-gap exclusion. Observation pauses while macOS is locked
-  or after 60 seconds without user input; every invalid interval starts a new
-  continuous activity block when valid observation resumes.
+  hysteresis, and sleep-gap exclusion. Locked and unavailable time is excluded.
+  Unlocked input-idle time remains excluded unless sustained supported AI work
+  is still measured, so long-running agents do not disappear merely because the
+  keyboard and pointer are untouched.
+- One explicit Start-to-Stop run now keeps one stable observation identity.
+  Sleep, lock, and inactivity create separate continuity periods without
+  inventing new observations. Timeline intervals preserve every valid measured
+  second across state changes, and filtered period counts use continuous blocks
+  rather than raw render fragments.
 - Clear states: **Active now**, **Ready**, **Monitoring**, and **Stopped**.
   Process presence alone never becomes active activity.
 - Durations retain seconds at every scale, including observations longer than
@@ -47,6 +53,12 @@ notarization remain future work.
 - The monitor is owned by the local service, not a browser tab. Closing the
   window does not end a session; stopping preserves the summary; clearing is a
   separate explicit action.
+- Service reconnect resumes the same observation without counting its offline
+  gap. An explicit Stop followed by Start creates a clean new observation and
+  never carries old totals, products, or timeline blocks into the new run.
+- Detailed timeline, one-minute per-app resource buckets, and monitor-overhead
+  samples remain bounded locally; cumulative observed and AI-active totals are
+  maintained independently and are not reduced when old visual blocks age out.
 - A persistent native AppKit/WebKit app installed into the current user's
   Applications folder by a one-time npm bootstrap. Later launches use normal
   macOS surfaces and do not require Terminal.
@@ -76,10 +88,12 @@ notarization remain future work.
 - Verified Ollama availability requires the exact local listener owner, a valid
   version response, and a valid tags response. Loaded state comes only from a
   valid `/api/ps` response.
-- A schema `2.0` candidate global aggregate based on valid observed seconds and
+- A schema `2.0` Global AI Preview aggregate based on valid observed seconds and
   AI-active seconds. It excludes names, process counts, paths, commands, chat,
   workspace, device identity, guess, and local scan ID. Review and consent are
-  separate; upload transport remains disabled.
+  separate. After explicit v2 native permission and one valid observed hour,
+  the app signs and syncs the allowlisted aggregate to Forkit.dev, keeping one
+  latest community-reported Preview row per stable local contribution key.
 - A 1080×1080 local share card with Share, Save PNG, Copy Image, and Copy
   Caption controls. It contains only measured totals and supported tool names.
 - A single Forkit.dev `/ai-footprint` page with an honest benchmark-forming
@@ -112,12 +126,12 @@ notarization remain future work.
   and stored local model records without attributing prompts or tasks.
 - A separate earlier real session crossed the previous 10-minute gate at exactly
   **600 valid seconds** and **598 AI-active seconds**. The current global
-  comparison candidate now requires **3,600 valid seconds** before the local
-  preview becomes available; no transport is enabled.
+  comparison requires **3,600 valid seconds** before a consented community
+  Preview aggregate becomes eligible for sync.
 
 ## Validation completed locally
 
-- TypeScript build and the complete local test suite: **119/119** tests passed.
+- TypeScript build and the complete local test suite: **135/135** tests passed.
 - Deterministic active → idle/locked → resumed lifecycle coverage confirms that
   paused time changes neither observed nor AI-active seconds and cannot bridge
   the longest continuous activity block.
@@ -142,8 +156,9 @@ notarization remain future work.
 
 ## Intentionally not enabled or not yet field-validated
 
-- No upload, verified global contribution, public ranking, account, registry
-  write, passport, Mint, Runtime_C2 write, telemetry, or production deployment.
+- No verified global contribution/ranking, account, passport registry
+  write, passport, Mint, Runtime_C2 write, or general telemetry. Only the
+  explicitly consented community Preview aggregate transport is enabled.
 - No Homebrew tap, signed direct download, or click installer.
 - No Developer ID signature, notarization, stapling, Gatekeeper distribution
   test, or clean external-Mac installation test.
@@ -171,5 +186,6 @@ claim that a cloud model is running locally.
 ## Smallest release gate
 
 Future expansion requires representative multi-device field accuracy, Intel Mac
-validation, and Apple signing/notarization. Global contribution remains closed
-until its separate server-side verification and abuse-control gate passes.
+validation, and Apple signing/notarization. Community Preview contribution is
+open under the v2 consent/integrity boundary; verified global ranking remains
+closed until its separate hardware-verification and abuse-control gate passes.