Initial public release of Apophis — invariant-driven automated API testing

docs/observe.md

@@ -2,6 +2,8 @@
 
 Runtime visibility and drift detection without blocking by default.
 
+Observe extends the invariant framework from [Invariant-Driven Automated Testing](https://arxiv.org/abs/2602.23922) (Malhado Ribeiro, 2021) to production environments: contracts run continuously against live traffic to detect behavioral drift without affecting requests.
+
 ## What Observe Does
 
 `apophis observe` validates your runtime observe configuration:
@@ -65,14 +67,38 @@ profiles: {
 }
 ```
 
-The `platform-observe` preset enables sampling at the preset level. Fine-tune per route with `x-observe-sampling` in your route schema.
+The `platform-observe` preset enables sampling. Configure the rate explicitly:
+
+```javascript
+profiles: {
+  'staging-observe': {
+    mode: 'observe',
+    preset: 'platform-observe',
+    routes: [],
+    sampling: 1.0  // 100% of requests observed
+  }
+}
+```
 
 ## Staging vs Production
 
 | Environment | Blocking | Sampling | Sink Required |
 |---|---|---|---|
-| Staging | No (default) | 10% | Yes |
-| Production | No (default) | 1% | Yes |
+| Staging | No (default) | 100% | Yes |
+| Production | No (default) | 100% | Yes |
+
+Default is `1.0` (100%). Configure lower rates for production explicitly:
+
+```javascript
+profiles: {
+  'prod-observe': {
+    mode: 'observe',
+    preset: 'platform-observe',
+    routes: [],
+    sampling: 0.1  // 10% of requests observed
+  }
+}
+```
 
 ## `--check-config` Flag
 
@@ -109,7 +135,6 @@ export default {
   presets: {
     'platform-observe': {
       name: 'platform-observe',
-      depth: 'standard',
       timeout: 10000,
       parallel: true,
       chaos: false,
@@ -138,3 +163,24 @@ export default {
   }
 };
 ```
+
+## Sink Endpoint Configuration
+
+Configure the reporting sink endpoint in your observe config:
+
+```javascript
+observe: {
+  sink: {
+    endpoint: 'http://collector.internal:4318'
+  }
+}
+```
+
+## Monorepo Validation
+
+For monorepos, use `apophis doctor --workspace` to validate observe configuration across all workspace packages. `observe` itself does not support `--workspace`; use `doctor` to check config in each package.
+
+## Mode Mismatch
+
+Profiles configured for `verify` mode will be rejected by `apophis observe`. Only profiles with `mode: 'observe'` are valid.
+```