chore: import upstream snapshot with attribution

sitemaps/hackernews/workflows/read-story.md

@@ -0,0 +1,57 @@
+---
+schema_version: 1.1
+workflow_id: read-story
+intent: read a HN story and its top-level comments
+last_verified: 2026-06-02
+source: global
+---
+
+## Goal
+
+拿到一条 HN story 的：标题 / URL / score / author / 时间 / top-level comments 列表。
+
+## State signature
+
+- entry: 任意 page，story id 或 URL 已知
+- success: 拿到 story object + comments array
+
+## Best path
+
+- adapter: opencli hackernews story <id>
+- adapter_health: healthy
+- preconditions: story id 已知
+- estimated_turns: 1
+
+## Fallback path
+
+如果 adapter 抛 typed error / 空 result（触发 `adapter_health_update: opencli hackernews story -> suspect`）：
+
+1. `opencli browser open https://news.ycombinator.com/item?id=<id>`
+2. action:expand_comment_tree in pages/item.md（如果有折叠）
+3. `opencli browser state` 拿 DOM
+4. parse story header (`tr.athing[id="<id>"]`) + comment tree (`tr.comtr` ids 数组)
+
+- estimated_turns: 3-4
+
+## Avoid
+
+- 不要从 /news 列表 page 推断 story 内容（列表只有标题 + score，无评论）
+- 不要 scrape 原文 URL（title link 指向外站，不是 HN 评论）
+- 不要并发 fan-out 全 comment tree 走 `item/<kid_id>.json` (rate limit 风险；用 adapter 已 throttle)
+
+## Re-entry checkpoints
+
+- 已 open /item?id=<id>，DOM ready → step 2 起
+- DOM 拿到但 expand 未做 → step 2 起
+- story + comments 已收集 → 完成
+
+## State validation
+
+- story.title 非空
+- comments array 长度 ≥ 0（dead story 可能 0）
+- 至少 story.by + story.time 字段存在
+
+## Stale markers
+
+- HN HTML 结构非常稳（10+ 年不大改）
+- Firebase API 是 read-only 公开服务，几乎不漂；endpoint:item 返回 schema 变化是大事件

sitemaps/hackernews/workflows/submit-story.md

@@ -0,0 +1,60 @@
+---
+schema_version: 1.1
+workflow_id: submit-story
+intent: submit a new story to HN (URL or text post)
+last_verified: 2026-06-02
+source: global
+---
+
+## Goal
+
+提交一条 story：title (≤80 char) + url XOR text body。URL post 或 Ask HN / Show HN 文本 post 二选一。
+
+## State signature
+
+- entry: 任意 page，logged_in，title 和 url(or text) 已准备
+- success: redirect to /newest 顶部出现新 story by 当前 user
+
+## Best path
+
+- adapter: null
+- adapter_health: broken （HN 无 write adapter，必须走 browser workflow）
+- preconditions: logged_in / title ≤ 80 char / url or text ready
+- estimated_turns: 4-5
+
+## Fallback path
+
+实际就是唯一 path（browser）：
+
+1. `opencli browser open https://news.ycombinator.com/submit`
+2. type title → `input[name="title"]`
+3. type url → `input[name="url"]` || type text → `textarea[name="text"]` （**互斥**，不能同时填）
+4. click `input[type="submit"]`
+5. 验证 redirect /newest，顶部新 story by 当前 user
+
+- estimated_turns: 4-5
+
+## Avoid
+
+- 不要同时填 url + text（HN 拒绝）
+- 不要 submit 超过 daily rate limit (throw_too_fast)
+- 不要重复 submit 同 URL（HN dedupe → 抛 "have submitted"）
+- title 不带 emoji（部分 emoji 引起 form 拒收）
+
+## Re-entry checkpoints
+
+- 已 open /submit，form empty → step 2 起
+- title filled 但 url/text 未填 → step 3 起
+- form 全填但未 submit → step 4 起
+- redirect /newest 且 story 出现 → 完成
+
+## State validation
+
+- redirect URL 含 `/newest` 或 `/item?id=<new-id>`
+- /newest 顶部 story.by 等于当前 user
+- title 完全匹配（HN 不修改 title）
+
+## Stale markers
+
+- /submit form field name (`title` / `url` / `text`) 几乎不变（10 年没改 form schema）
+- HN 偶尔加 captcha 给 new user (< 7 天账号)

sitemaps/hackernews/workflows/upvote.md

@@ -0,0 +1,53 @@
+---
+schema_version: 1.1
+workflow_id: upvote
+intent: upvote a story or comment
+last_verified: 2026-06-02
+source: global
+---
+
+## Goal
+
+对一条 story 或 comment 投上票。需 login，不可投自己内容。
+
+## State signature
+
+- entry: 任意 page，logged_in，目标 item id 已知
+- success: vote arrow 灰显（已投状态）
+
+## Best path
+
+- adapter: null
+- adapter_health: broken （HN 无 write adapter，必须走 browser workflow）
+- preconditions: logged_in / target item id 已知 / 不是自己内容
+- estimated_turns: 2
+
+## Fallback path
+
+唯一 path：
+
+1. `opencli browser open https://news.ycombinator.com/item?id=<id>` 或 /news 找到该 item
+2. action:upvote in pages/item.md
+
+- estimated_turns: 2
+
+## Avoid
+
+- 不要 vote 自己的 story / comment（HN NoOp，arrow 不显示）
+- 不要快速连续 vote 多条（rate limit，~10s 内 >5 票触发 cool-down）
+- 不要 hardcode vote URL（必须从页面 `a[id="up_<id>"]` 提 csrf token）
+
+## Re-entry checkpoints
+
+- 已 open /item?id=<id>，arrow visible → step 2
+- arrow 已灰 → 完成（idempotent，不重复 click）
+
+## State validation
+
+- `a[id="up_<id>"]` 从有效变灰（class 含 `nosee` 或 visibility hidden）
+- 自己 user profile karma +1（异步，可能延迟）
+
+## Stale markers
+
+- HN vote URL 含 auth token，token 生成机制偶尔小调（极罕见）
+- pitfall:vote_requires_login_and_csrf 一直有效