adr: define project purpose and scope

Author: Arturo R Montesinos

docs/adr/0001-project-purpose-and-scope.md

@@ -0,0 +1,67 @@
+# ADR-0001: Project Purpose and Scope
+
+- Status: Accepted
+- Date: 2025-12-07
+
+## Context
+
+The `odsview-cli-python` project aims to provide a way to inspect
+LibreOffice Calc `.ods` spreadsheets in environments where graphical
+applications are impractical or unavailable, such as:
+
+- SSH sessions to remote servers.
+- Headless or low-bandwidth environments.
+- Terminal-only contexts like Termux on Android.
+
+Today, opening `.ods` files typically requires a full GUI office suite
+(e.g., LibreOffice). X11 forwarding or remote desktops are heavyweight
+and often fragile. There is no small, focused CLI tool that plays a
+similar role for `.ods` files as `less` does for text files.
+
+The accompanying `docs/curation/BLUEPRINT.md` document captures an
+aspirational design for such a tool, but per the Software Curatorship
+baseline, **implemented behavior and ADRs are authoritative** once they
+exist.
+
+## Decision
+
+We define `odsview-cli-python` as:
+
+> A minimal, read-only, terminal-based viewer for `.ods` spreadsheet
+> files, designed to run well over SSH and in constrained terminal
+> environments.
+
+Key aspects of this decision:
+
+- **Read-only**: the tool will not modify `.ods` files.
+- **Terminal-focused**: output is rendered as text tables suitable for
+  standard terminals; no GUI dependencies.
+- **CLI-first**: interaction happens via a command-line interface
+  (e.g., `odsview path/to/file.ods [options]`).
+- **Minimal dependencies**: prefer a small, reliable ODS parsing
+  library and otherwise rely on the Python standard library unless an
+  ADR justifies additional dependencies.
+- **Initial target format**: `.ods` only. Support for other formats
+  (such as `.xlsx`) may be considered in future ADRs.
+
+This ADR also establishes that the blueprint’s vision is the primary
+source of inspiration for future features, but **ADRs and tested
+behavior override the blueprint wherever there is a conflict**.
+
+## Consequences
+
+- Future work will be evaluated against this purpose: features that do
+  not serve the read-only terminal viewer use case require strong
+  justification.
+- Editing capabilities, GUI front-ends, or broad spreadsheet
+  manipulation APIs are explicitly out of scope unless reintroduced by
+  a new ADR.
+- The CLI contract (inputs, outputs, exit codes) will be refined in
+  `AI_CURATOR_RECIPE.md` Appendix A and backed by tests as behavior is
+  implemented.
+- Library choice for reading `.ods` files (e.g., `ezodf` or another
+  library) will be decided and documented in a separate ADR (e.g.,
+  ADR-0002) once implementation begins.
+- The ADR index in `docs/adr/README.md` must be kept up to date so that
+  curators and contributors can quickly discover this foundational
+  decision.

docs/adr/README.md

@@ -1,12 +1,3 @@
-# Architecture Decision Records (ADR)
+# Architecture Decision Records
 
-This directory contains Architecture Decision Records for the
-`odsview-cli-python` project. ADRs capture **why** significant decisions
-were made, not just **what** was implemented.
-
-## Index
-
-> Maintained by tooling (e.g. `scripts/check_adr_index.py`).
-> Each entry should be updated whenever ADRs are added or statuses change.
-
-- _No ADRs recorded yet._
+- ADR-0001: [Project Purpose And Scope](0001-project-purpose-and-scope.md)