import io

p = 'docs-site/src/harness-contract/api.md'
s = io.open(p, encoding='utf-8').read()

old = "`idle` also arms the echo gate (below) unless `--no-gate`."
new = ("`idle` also arms the echo gate (below) unless `--no-gate` — **the arming is\n"
       "unconditional; the *fire* waits for age.**")
assert s.count(old) == 1
s = s.replace(old, new)

old = '''### `api echo-gate <set|clear> <id>`

Manage the echo-gate sentinel directly. The gate marks "a summarization may
be needed when this session ends without a graceful signoff" — `state idle`
sets it as a side effect; a graceful signoff clears it.'''
new = '''<!-- [doc->REQ-ECHO-IDLE-AGE-GATE] the surface half: two arms, which one `state idle` arms, which one this verb arms, and the age discipline that separates their FIRES -->
### `api echo-gate <set|clear> <id>`

Manage the echo-gate sentinel directly. The gate marks "a summarization may
be needed when this session ends without a graceful signoff" — `state idle`
sets it as a side effect; a graceful signoff clears it.

**The gate has two arms, and they fire on different rules.**

| arm | armed by | fires |
| --- | --- | --- |
| **edge** | an attention change — detach, attention shift, `spt suspend` — or `echo-gate set` | **immediately**, at the next pulse |
| **work** | every `api state idle`, i.e. every turn end | only once that report is **15 minutes old** |

The edge arm is ungated because its whole value is timeliness: it fires when
attention is leaving, and an echo that arrives after the agent is gone is an
echo that did not happen. The work arm is age-gated because a turn end is not
by itself news — an agent reports dozens an hour, and summarizing each one
would spend a model call to say almost nothing. Fifteen minutes of accumulated
work is the unit that has something in it.

They are **two sentinel files**, not one file with a flag, so an idle report
can never overwrite a pending attention-change fire and quietly turn an urgent
echo into a delayed one.

`set` arms the **edge** arm — an explicit set means *now*, and routing it to
the age-gated arm would silently mean *within fifteen minutes*. `clear` clears
**both**: you asked for no pending echo, so no arm is left standing.

The window is a constant, not a knob. If you want it configurable, that is its
own request rather than a flag added here.'''
assert s.count(old) == 1
s = s.replace(old, new)

io.open(p, 'w', encoding='utf-8', newline='\n').write(s)
print('ok')