# Read Boxnote

> Convert Box Notes (.boxnote files) into readable Markdown. Use whenever you need to read, search, or quote the society's meeting notes, calendars, event proposals, or member lists — most of the archive is stored as .boxnote (ProseMirror JSON) which is not human-readable as-is. Also builds a full-text index of the whole archive.

- Skill: `faaz17/read-boxnote` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add faaz17/read-boxnote`
- Raw SKILL.md: https://api.skillmd.com/api/skills/faaz17/read-boxnote/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Faaz17 (https://skillmd.com/u/faaz17)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/faaz17/read-boxnote

---


# Reading Box Notes

The society archive is mostly `.boxnote` files — Box Notes stored as ProseMirror
JSON. They can't be read directly. `boxnote_to_text.py` (stdlib Python only,
lossless UTF-8) renders them to clean Markdown: headings, bullet/numbered lists,
checkboxes, tables, links, and formatting.

## When to use

- You need to read/search/quote any `.boxnote` (meeting notes, calendars,
  proposals, rosters).
- Someone added or edited Box Notes and the `_converted/` mirror is stale.
- You want one searchable file covering the entire archive.

## Commands

Run from the society root (`Scoiety Folders/`):

```bash
# One note → screen
python ".claude/skills/read-boxnote/boxnote_to_text.py" "2022 - 2023/Autumn 2022/Meeting #1.boxnote"

# One note → a .md file
python ".claude/skills/read-boxnote/boxnote_to_text.py" "path/to/Note.boxnote" -o out.md

# Convert EVERY .boxnote into a mirror tree under _converted/
python ".claude/skills/read-boxnote/boxnote_to_text.py" --all "."

# Build one master full-text index of every note
python ".claude/skills/read-boxnote/boxnote_to_text.py" --index "." -o "_converted/ARCHIVE_INDEX.md"
```

## Normal workflow

1. **To read/search the archive:** prefer the already-generated `_converted/*.md`
   files and `_converted/ARCHIVE_INDEX.md`. Grep the index to find the note, then
   open the specific converted file for full context.
2. **After Box Notes change:** re-run `--all` then `--index` to refresh.
3. **Do not edit** files in `_converted/` by hand — they're regenerated. Edit the
   source `.boxnote` in Box, or a real doc in the term folder.

## Notes

- Windows + Python 3.11 confirmed working; no third-party packages needed.
- Output is UTF-8. Terminal (Git Bash) may show `�` for smart quotes/bullets —
  that's a console display quirk only; the written `.md` files are correct.
- Old notes' manual `·` bullets and non-breaking spaces are normalized to clean
  Markdown automatically.