docs: recover Hwping-native spec and research memo

project: hwping
agent: codex
role: worker
artifacts: LOG-20260409-001, RSH-20260409-001

Author: LPFchan

SPEC.md

@@ -1,84 +1,173 @@
 # Hwping Spec
 
-This file is the canonical statement of what Hwping is supposed to be.
+This file is the canonical durable statement of what Hwping is supposed to be.
 
-## Identity
+It is not the implementation-status report or milestone tracker. Current state lives in `STATUS.md`; accepted future sequencing lives in `PLANS.md`.
+
+## Project Identity
 
 - Project: Hwping
 - Canonical repo: `https://github.com/LPFchan/Hwping`
 - Project id: `hwping`
 - Operator: `LPFchan`
 - Last updated: `2026-04-09`
-- Related decisions: `DEC-20260409-001`
+- Key decisions: `DEC-20260409-001`, `DEC-20260409-002`, `DEC-20260409-003`, `DEC-20260409-004`, `DEC-20260409-005`
+
+## What Hwping Is
+
+Hwping is a native macOS-focused HWP reader product and downstream fork of upstream `rhwp`.
+
+It is meant to let macOS users open `.hwp` and `.hwpx` documents from familiar Apple-platform surfaces, read them comfortably, preview them in Finder, automate simple read-only workflows, and export or print them without turning the shared document engine into app code.
+
+## Product Principles
+
+### v1 Is A Reader
+
+- Prioritize opening, reading, navigation, search, printing, PDF export, Quick Look, and automation.
+- Favor Preview-like document viewing and TextEdit-like macOS document-app conventions.
+- Keep full editing, annotations, collaboration, cloud sync, and complex authoring workflows out of the v1 promise.
+
+### Keep Engine And Product Separate
+
+- Rust owns the upstream-aligned HWP/HWPX parser, model, layout, renderer, serializer, and CLI behavior.
+- Downstream facade and FFI layers own the app-facing capability boundary.
+- Swift and Apple-platform targets own document lifecycle, windows, menus, Finder integration, Quick Look, App Intents, Shortcuts, and app UI.
+- AppKit, SwiftUI, PDFKit, Quick Look, Finder, App Intents, and Shortcuts behavior must not leak into `crates/rhwp/`.
+
+### Share One Capability Boundary
+
+The main app, Quick Look Preview extension, Quick Look Thumbnail extension, Shortcuts/App Intents, smoke targets, and future automation should reuse one document-loading and rendering capability boundary instead of each surface inventing its own engine path.
+
+## Intended System Shape
+
+```text
+user document (.hwp / .hwpx)
+  -> Hwping.app (NSDocument-based)
+  -> Quick Look Preview extension
+  -> Quick Look Thumbnail extension
+  -> App Intents / Shortcuts
+
+each surface
+  -> Apple-platform call layer
+    -> hwping-ffi
+      -> hwping-core
+        -> rhwp
+          -> parser / model / layout / renderer / serializer
+```
+
+## Core Surfaces
+
+### `crates/rhwp/`
+
+Upstream-aligned shared engine area.
+
+Owns:
 
-## Product Thesis
+- HWP and HWPX parsing
+- document model
+- layout and pagination
+- foundational SVG, PDF, bitmap, or preview-ready rendering paths
+- serialization
+- platform-independent CLI and debugging paths
 
-Hwping is a macOS-focused downstream fork and product workspace built on top of upstream `rhwp`. It exists to ship a native HWP reader stack for Apple platforms while keeping the shared HWP and HWPX engine as upstream-aligned and syncable as possible.
+Default rule: treat changes here as upstreamable unless there is a concrete recorded reason for a local compatibility patch.
 
-## Primary User And Context
+### `crates/hwping-core/`
 
-- Primary operator: Hwping maintainer and collaborators
-- Primary environment: a Cargo workspace with downstream Rust, FFI, and Apple-platform targets
-- Primary problem being solved: deliver reliable HWP and HWPX reading workflows on macOS without letting the fork drift into an unsyncable multi-product repository
-- Why this matters: reading correctness, product focus, and upstream sync cost all depend on keeping shared engine work and Apple-platform product work sharply separated
+App-facing Rust facade.
 
-## Primary Workspace Object
+Expected operation families:
 
-The primary user-facing object is an HWP or HWPX document rendered through an upstream-aligned engine and delivered through native macOS surfaces.
+- open a document from bytes or path
+- report document info, page count, page size, and first-page metadata
+- render preview-ready PDF or page images
+- render first-page thumbnail data
+- extract text and search for a query
+- export PDF
+- normalize product-facing errors
 
-## Canonical Interaction Model
+### `crates/hwping-ffi/`
 
-1. A user opens an HWP or HWPX document from the app, Finder, or a Quick Look surface.
-2. Hwping parses and renders the document through `crates/rhwp/`.
-3. Downstream facade and FFI layers expose metadata, page data, and rendered output to Apple-platform callers.
-4. The app or extension presents reading, preview, search, export, and system integration workflows.
-5. Maintainers preserve shared-core correctness and review upstream changes through `upstream-intake/`.
+Swift-facing ABI boundary.
 
-## Core Capabilities
+Owns conversion of strings, paths, bytes, handles, errors, metadata structs, preview bytes, ownership, and lifetime rules.
 
-- Capability: upstream-aligned HWP and HWPX parsing and rendering
-  - Why it exists: Hwping needs accurate document understanding and output while staying cheap to sync with upstream `rhwp`
-  - What must remain true: shared-core fixes should stay upstreamable or at least upstream-shaped unless a concrete Hwping-only reason exists
-- Capability: downstream macOS product boundary
-  - Why it exists: Hwping needs app, FFI, Quick Look, and Apple integration without contaminating the engine core
-  - What must remain true: Apple-platform behavior stays outside `crates/rhwp/`
-- Capability: disciplined repo operations and upstream intake
-  - Why it exists: a downstream fork needs explicit truth, plans, decisions, worklogs, and recurring upstream review
-  - What must remain true: root truth docs, provenance records, and `upstream-intake/` remain canonical
+### `apps/` And `extensions/`
 
-## Invariants
+Downstream Apple-platform product targets.
 
-- `crates/rhwp/` is the upstream-aligned engine area.
-- Apple-platform code lives in downstream layers such as `crates/hwping-core/`, `crates/hwping-ffi/`, `apps/`, and `extensions/`.
-- Root `SPEC.md`, `STATUS.md`, and `PLANS.md` hold canonical project truth, current state, and accepted future direction.
-- `upstream-intake/` is the canonical recurring upstream-review module.
-- `mydocs/` stores shared technical, troubleshooting, and manual material that supports but does not replace the root truth docs.
-- Hwping-specific accepted direction and architecture decisions live in root docs and `DEC-*` records, not in a separate `mydocs/hwping/` subtree.
+Intended targets:
+
+- main `NSDocument`-based Hwping app
+- Quick Look Preview extension
+- Quick Look Thumbnail extension
+- smoke and integration targets needed to validate the app boundary
+
+## Native Reader Experience
+
+The target app should behave like a normal macOS document app:
+
+- Finder double-click opens a document in Hwping.
+- Recent documents, windows, tabs, state restoration, printing, and standard app menus behave consistently with macOS expectations.
+- Space bar Quick Look preview works without launching the full app UI.
+- Finder thumbnails are fast enough not to make ordinary folder browsing feel broken.
+- Search, page movement, zooming, fit behavior, printing, and PDF export use one command model across menus, shortcuts, toolbar actions, intents, and automation when practical.
+
+## Viewing Strategy
+
+The accepted v1 direction favors a PDF-backed viewing path:
+
+```text
+.hwp / .hwpx
+  -> rhwp parsing and layout
+  -> preview-ready PDF generation
+  -> native PDF-backed viewing or preview surface
+```
+
+This path should get Hwping to native scrolling, zooming, printing, and Preview-like behavior faster than a custom page view. It must not prevent a direct page renderer later if text selection, accessibility, overlays, search quality, or navigation demands it.
+
+## Error, Cache, And Quality Expectations
+
+User-visible errors should stay short and actionable, grouped around cases like open failure, corrupted document, unsupported feature, font substitution difference, render failure, permission failure, or file-access failure.
+
+Likely cache targets include preview PDF, first-page thumbnail, page size, page count, document metadata, and render options. Cache invalidation should be able to account for file identity, file size, modification time, render parameters, and engine version.
+
+Quality expectations:
+
+- Ordinary documents should show a first useful reading surface quickly.
+- Quick Look and thumbnail paths should have tighter budgets than the full app.
+- App-shell menus, buttons, search UI, zoom, opening, and page movement should be keyboard-accessible and VoiceOver-friendly.
+- Document-content accessibility can improve after v1, but app-shell accessibility is part of the baseline product quality.
+
+## Repository Operating Contract
+
+Hwping uses the repo-template model, with Hwping-specific rules in `REPO.md`.
+
+- `SPEC.md`, `STATUS.md`, and `PLANS.md` hold canonical truth, current state, and accepted future direction.
+- `records/decisions/` holds durable decisions.
+- `records/agent-worklogs/` holds useful execution history.
+- `research/` holds reusable exploration.
+- `upstream-intake/` holds recurring upstream-review artifacts.
+- `mydocs/tech/`, `mydocs/troubleshootings/`, and `mydocs/manual/` hold deeper shared technical, investigation, and manual material.
+
+Do not recreate a dedicated `mydocs/hwping/` tree.
 
 ## Non-Goals
 
-- web demo hosting
+- full editing for v1
+- annotations and collaboration for v1
+- cloud sync for v1
+- an iOS release alongside the first macOS app
+- web demo hosting in the main Hwping tree
 - npm package distribution for old web or editor surfaces
 - VS Code extension distribution
-- legacy browser-only infrastructure
-
-## Main Surfaces
-
-- Surface: `crates/rhwp/`
-  - Purpose: upstream-aligned parser, model, renderer, serializer, and CLI engine
-  - Notes: treat engine changes as upstreamable by default
-- Surface: `crates/hwping-core/`, `crates/hwping-ffi/`, `apps/`, and `extensions/`
-  - Purpose: downstream product and Apple-platform integration surfaces
-  - Notes: keep these boundaries clean and product-owned
-- Surface: `SPEC.md`, `STATUS.md`, `PLANS.md`, `INBOX.md`, `research/`, `records/`, and `upstream-intake/`
-  - Purpose: canonical repo operating surfaces
-  - Notes: keep truth, intake, research, decisions, logs, and upstream review distinct
-- Surface: `mydocs/`
-  - Purpose: shared technical notes, troubleshooting references, and manuals
-  - Notes: use these docs for depth, not as a substitute for root truth docs or decision records
+- legacy browser-only infrastructure kept only for history
 
 ## Success Criteria
 
-- Hwping ships a native macOS reader stack without reabsorbing removed upstream product surfaces.
-- Shared engine work remains cheap to sync with upstream `rhwp`.
-- Maintainers can answer what Hwping is, what is true now, what is accepted next, what was decided, and what happened by reading the repo itself.
+Hwping succeeds when:
+
+- a macOS user can open an HWP/HWPX document, preview it, navigate it, search it, print it, export it, and automate basic read-only tasks through native-feeling surfaces
+- shared engine correctness keeps improving without product code contaminating upstream-aligned code
+- upstream `rhwp` changes can be reviewed and adapted deliberately
+- maintainers can recover current truth, accepted direction, key decisions, research, execution history, and upstream-intake outcomes from the repo itself

records/agent-worklogs/LOG-20260409-001-repo-template-migration-bootstrap.md

@@ -65,3 +65,12 @@ Implement the full `LPFchan/repo-template` operating model in the Hwping reposit
 - Output: confirmed that the repo now contains the root truth stack, provenance directories, and canonical upstream-review subsystem expected by the adopted operating model
 - Blockers: none
 - Next: keep routing future durable work through the root surfaces and use commit provenance trailers on artifact-bearing commits
+
+## Entry 2026-04-09 17-48-43 KST
+
+- Action: reconciled over-normalized spec and research surfaces against retired `mydocs/hwping/` sources, current root docs, and current lightweight repo-template guides
+- Files touched: `SPEC.md`, `research/README.md`, `research/RSH-20260409-001-textedit-menubar-reference.md`, this worklog
+- Checks run: `git diff --check`; byte-for-byte comparison of `research/README.md` against repo-template scaffold; candidate doc enumeration; history inspection around `8255216` and `833f402`
+- Output: restored Hwping-native architecture, product-scope, reader-experience, repo-boundary, and TextEdit-reference detail while keeping artifact provenance and canonical root-doc routing
+- Blockers: none
+- Next: commit the reconciliation as a docs/provenance update; leave Rust validation for code-bearing changes

research/README.md

@@ -25,56 +25,23 @@ Each memo should begin with:
 - `Opened: YYYY-MM-DD HH-mm-ss KST`
 - `Recorded by agent: <agent-id>`
 
-## Default Shape
+## Minimum Content
 
-- Metadata
-- Research question
-- Why this belongs to this repo
-- Findings
-- Promising directions
-- Dead ends or rejected paths
-- Recommended routing
+A research memo should usually make these things recoverable:
 
-Use that section order by default unless the research genuinely needs a different structure.
+- what question or area was explored
+- the findings worth preserving
+- any important rejected paths, open questions, or follow-up routes
 
-## Canonical Example
+The exact section names and order can vary by project.
 
-```md
-# RSH-20260409-001: TextEdit Menu Bar Reference For Hwping
+## Suggested Shapes
 
-Opened: 2026-04-09 05-29-07 KST
-Recorded by agent: codex-20260409-full-repo-template-migration
+Any of these are acceptable when they fit the repo better:
 
-## Metadata
+- question -> findings -> next steps
+- topic -> evidence -> conclusion
+- exploration notes -> recommendations
+- short memo with lightweight headings
 
-- Status: completed
-- Question: What menu-bar baseline should Hwping use for the first complete macOS reader app?
-- Related ids: DEC-20260409-004
-
-## Research Question
-
-What menu-bar baseline should Hwping use for the first complete macOS reader app?
-
-## Why This Belongs To This Repo
-
-Hwping is building a native macOS document app, so a reusable menu-bar baseline belongs in repo research rather than in transient chat notes.
-
-## Findings
-
-- TextEdit is a useful baseline for standard macOS document-app menu ordering and grouping.
-- Hwping v1 should preserve native document-app expectations while staying read-only.
-
-## Promising Directions
-
-- Use TextEdit as a baseline when evaluating first-pass Hwping menu structure.
-- Capture accepted menu decisions in `records/decisions/` instead of keeping them only in research.
-
-## Dead Ends Or Rejected Paths
-
-- Blind command-for-command copying from TextEdit without checking Hwping's read-only scope.
-
-## Recommended Routing
-
-- Keep this memo as reusable reference material.
-- Move accepted product decisions into `DEC-*` records.
-```
+Keep the memo normalized and readable, but do not force one house style across every repo.