118 lines
4.7 KiB
Markdown
118 lines
4.7 KiB
Markdown
# ipfs.kane-il.us — Content & Path Conventions (v1)
|
|
|
|
## 0. Scope
|
|
- Public-only repository for IPFS gateway publishing.
|
|
- Text formats only: `*.md`, `*.txt`, `*.jsonl`.
|
|
- No binaries (pdf, images, video, archives) — describe them in markdown for accessibility.
|
|
- All timestamps are **UTC**.
|
|
|
|
## 1. Top-level categories (roots)
|
|
```
|
|
/legal
|
|
/civics
|
|
/naics
|
|
/barter
|
|
/w3pbs
|
|
/onet
|
|
/_log # public minimal publish log
|
|
```
|
|
- Root-level design documents (e.g. CONVENTIONS, README, checklists) may be placed directly at repo root.
|
|
- To avoid collisions, these use versioned filenames like `CONVENTIONS_v1.md`, `CONVENTIONS_v2.md`.
|
|
|
|
## 2. Naming rules (files & dirs)
|
|
- **Lowercase**, **ASCII**, **underscores** for word separators.
|
|
- Filenames must start with **digits-only ISO UTC timestamp**:
|
|
- `YYYYMMDDThhmmssZ_<slug>.md`
|
|
- Exception: root design documents, which follow `<NAME>_vN.md`.
|
|
|
|
## 3. Immutability
|
|
- No “latest” aliases, no mutable pointers.
|
|
- No per-directory index files; rely on gateway directory listing.
|
|
- Every publish is additive; removals are exceptional (court/admin error).
|
|
|
|
## 4. LEGAL
|
|
### 4.1 research (jurisdiction-first, typed entities)
|
|
Path template:
|
|
```
|
|
/legal/research/{scope}/{segment}/{subject}/...
|
|
```
|
|
- `scope ∈ {county|town|township|individual|organization}`
|
|
- If `scope=organization` or `individual`, use typed entity layering:
|
|
```
|
|
/legal/research/{scope}/{kind}/{name}/{subject}/...
|
|
kind ∈ {governance|economic|domestic|technical|infrastructure|virtual}
|
|
```
|
|
- Otherwise:
|
|
```
|
|
/legal/research/{scope}/{jurisdiction_name}/{subject}/...
|
|
```
|
|
|
|
### 4.2 court → cases
|
|
Path template:
|
|
```
|
|
/legal/court/{court_id}/{case_id}/(filings|evidence|orders|docket|notes|transcripts|exhibits)/
|
|
```
|
|
- `court_id` will follow Kane County authoritative naming.
|
|
- `case_id` sanitized to lowercase/underscores; original case identifier stored inside the markdown.
|
|
|
|
## 5. Other categories
|
|
- **civics/**: governance, policy, licenses, standards → plain markdown.
|
|
- **naics/**: subdirectories by NAICS code.
|
|
- **barter/**: web2py assets and git-oriented text/config (no binaries).
|
|
- **w3pbs/**: mailing lists, streaming, chat, forums; html/gemini as text or markdown summaries.
|
|
- **onet/**: O*NET taxonomy (latest), directories from O*NET categories.
|
|
|
|
## 6. Publish log (public, minimal)
|
|
- Location: `/_log/publish.jsonl`
|
|
- One JSON object per line with fields:
|
|
- `ts` (UTC string),
|
|
- `event` (e.g. `"publish"`),
|
|
- `man` (manifest path),
|
|
- `sig` (signature path),
|
|
- `signer` (e.g. publisher@ipfs.kane-il.us),
|
|
- `ns` (signature namespace, canonical = `ipfspublish`),
|
|
- `repo` (e.g. `w3pbs/ipfs.kane-il.us`),
|
|
- `commit` (git hash).
|
|
- Past entries retained forever.
|
|
- Fields like `manifest_cid`, `paths`, and `tag` may be added in future expansions.
|
|
|
|
## 7. Signatures
|
|
- All manifests are signed with **SSH-sig** using the deploy key.
|
|
- Canonical namespace: **`ipfspublish`**.
|
|
- Verification uses `allowed_signers` file with principal `publisher@ipfs.kane-il.us`.
|
|
|
|
## 8. Guardrails (deny)
|
|
- Private/staging content never enters this repo.
|
|
- Deny common tool dirs: `.git/`, `.github/`, `.vscode/`, caches, temp files.
|
|
- Deny binaries by extension (see `.gitignore`).
|
|
|
|
## 9. Accessibility
|
|
- For any non-text source (e.g., a PDF elsewhere), store a **descriptive .md**: what it is, where it exists, date, and an accessible summary.
|
|
|
|
## 10. Examples
|
|
```
|
|
/legal/research/county/kane/zoning/20250828T140000Z_buffer_requirements.md
|
|
/legal/court/il_kane_circuit/23_ch_000123/filings/20250828T142500Z_plaintiff_motion.md
|
|
/naics/541611/20250828T150000Z_procurement_policy.md
|
|
/onet/architecture_and_engineering/20250828T160000Z_job_function_overview.md
|
|
```
|
|
|
|
## 11. Operator Utilities
|
|
* **Primary interface:** Operators are expected to use **Midnight Commander (`mc`)** as the daily driver for browsing, staging, and publishing files.
|
|
* **Backup scripts:** Deterministic shell scripts are maintained under `/tools/`.
|
|
|
|
* Purpose: fallback when `mc` is unavailable, misconfigured, or fails mid-operation.
|
|
* Behavior: scripts normalize filenames, run publish steps, and include `--dry-run` modes.
|
|
* Example:
|
|
|
|
* `publish-rename` → normalize names to required conventions.
|
|
* `publish-doc` (planned) → chain the full publishing flow.
|
|
* **mc integration:** These scripts may also be bound to the mc user menu (`~/.config/mc/mc.menu`) so that the same deterministic actions can be triggered via `F2`.
|
|
* **Automation:** Because they are standalone, scripts can also be called in batch or from other automation tooling if desired.
|
|
|
|
**Principle:**
|
|
|
|
* **mc = primary operator UX** (interactive, user-friendly).
|
|
* **scripts = deterministic backup + automation hooks**.
|
|
* Both are valid, auditable, and kept in sync with these conventions.
|