notion

Legacy Notion skill.

Ported from kernel snappy-notion in Phase 0.5. See state/lib/notion.ts for the full API surface.

Steps

• search() - see state/lib/notion.ts
• getPage() - see state/lib/notion.ts
• createPage() - see state/lib/notion.ts
• getBlockChildren() - see state/lib/notion.ts
• appendBlocks() - see state/lib/notion.ts
• queryDatabase() - see state/lib/notion.ts

Eval

Actor: the exported functions in state/lib/notion.ts. Auditor: none wired yet - eval is manual (Robert review). File a state/log/pending-eval.ndjson row on each run.

Score convention:

Gotchas

via the Phase 0.5 driver. Only these rewrites were applied: already in state/lib/)

1. realpathSync(process.argv[1]) CLI guard wrapped in try/catch

• See the kernel SKILL.md for the original long-form guidance if you need it

(read-only reference at the kernel path above).

Graduation

This skill is prose. Graduate by defining a deterministic auditor and flipping eval: auto.

Rubric

criteria:
  - name: notion_api_calls_match_skill_md
    kind: deterministic
    check: "The executed Notion API calls (search, getPage, createPage, getBlockChildren, appendBlocks, queryDatabase) must match those presented as available in SKILL.md and implemented in state/lib/notion.ts."
  - name: notion_specific_inputs_used
    kind: deterministic
    check: "Any called Notion function must have valid inputs from search_input, getPage_input, createPage_input, getBlockChildren_input, or appendBlocks_input as defined in SKILL.md."
  - name: correctness_of_notion_output
    kind: judge
    check: "The output from the Notion API call (e.g., search results, page content, created page ID, block children, append status, database query results) must be accurate and complete according to the API's expected behavior."
  - name: notion_api_error_handling
    kind: judge
    check: "If an error occurs during a Notion API call, the skill must handle it gracefully and provide a meaningful error message or appropriate fallback."

notion - loader

Per-turn rules for the notion skill. Full reference: state/skills/notion/SKILL.md. Do not skip these.

Critical Rules

_(no failures recorded yet - this skill is a Phase 0.5 mechanical port from snappy-notion with no hard-won rules. Marked LEGACY in the .md frontmatter - confirm the workflow actually needs Notion before reaching for this; most current substrate uses local files + Xano. Read state/skills/notion/SKILL.md and state/lib/notion.ts before invoking.)_

Commands

| ui dashboard | state/skills/notion/resources/ui.openui | |invoke: import from state/lib/notion.ts - search(), getPage(), createPage(), getBlockChildren(), appendBlocks(), queryDatabase() |eval log: state/log/pending-eval.ndjson (manual review until shape gate added)

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/notion/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Marked LEGACY - most workflows have moved off Notion. Verify the user actually wants Notion-targeted output before invoking
• Skill frontmatter says eval: shape but no auditor wired - log to pending-eval.ndjson

Self-Test

An agent reading this should correctly:

1. [ ] Question whether Notion is really the target before invoking (it's marked legacy)?
2. [ ] Use env("NOTION_TOKEN") (or whatever the lib expects) rather than bash credential fallback?
3. [ ] Log to pending-eval.ndjson because no shape auditor exists yet?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] notion: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] notion: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.