Update preface and quick start guide

[jdecarolis]

Rewrote large portions of preface.rst and updated the database description in quick_start.rst.

Summary by CodeRabbit

• Documentation
  • Expanded explanations of core capabilities and design philosophy
  • Reorganized quick start guide with clearer database setup guidance
  • Updated examples and schema documentation for improved usability

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Documentation expanded and restructured across two files. Preface section enriched with detailed narrative on ESOM characteristics, components, and open-source motivations. Quick Start guide rewritten to emphasize relational database terminology, schema-driven design, and updated example file paths, replacing prior DAT-file-centric descriptions.

Changes

Cohort / File(s)	Summary
Documentation narrative expansion docs/source/preface.rst	Expanded "What is Temoa?" and "Why Temoa?" sections with comprehensive explanations of ESOM characteristics, time handling, components, licensing, open-source ecosystem, and historical context.
Quick Start restructuring docs/source/quick_start.rst	Reworded usage guidance to emphasize relational database approach; replaced DAT-file terminology with database schema concepts (tables, primary/foreign keys); updated examples from data_files/temoa_utopia.sql to data_files/example_dbs/utopia.sql and schema references to temoa_schema_v4.sql; added relational database advantages rationale.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

docs

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: updating documentation in preface.rst and quick_start.rst files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch doc_updates

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5ddcf8b and 5d85d6b.

📒 Files selected for processing (2)

• docs/source/preface.rst
• docs/source/quick_start.rst

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: setup and test (macos-latest, 3.13)
• GitHub Check: setup and test (macos-latest, 3.12)
• GitHub Check: setup and test (windows-latest, 3.12)
• GitHub Check: setup and test (windows-latest, 3.13)

🔇 Additional comments (3)

docs/source/quick_start.rst (3)

129-176: Database explanation is clear and well-presented.

The introduction to relational databases, primary keys, foreign keys, and referential integrity is accurate and appropriately tailored for an introductory audience. The emphasis on using databases to catch typos through constraints is practical and valuable.

---

139-155: SQL example is syntactically correct.

The CREATE TABLE and INSERT examples follow SQLite conventions correctly. The primary key definition and foreign key constraint are properly structured.

---

226-231: File path references are accurate and verified.

Both updated file paths referenced in the documentation exist in the repository:

• data_files/example_dbs/utopia.sql ✓
• data_files/temoa_schema_v4.sql ✓

No action needed.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix spelling errors in documentation.

Lines 50 and 53 contain misspellings:

• Line 50: "seemlessly" → should be "seamlessly"
• Line 53: "inpout data" → should be "input data"

These need correction before release to maintain documentation quality.

🔎 Proposed fixes

- seemlessly integrates with the broader Python
+ seamlessly integrates with the broader Python

- The model maintains a
- strict distinction between source code and the inpout data on which it operates.
+ The model maintains a
+ strict distinction between source code and the input data on which it operates.

Also applies to: 53-53

🤖 Prompt for AI Agents

In docs/source/preface.rst around lines 50 and 53, fix the spelling mistakes:
change "seemlessly" on line 50 to "seamlessly" and change "inpout data" on line
53 to "input data"; update those words in the file so the documentation uses the
correct spellings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix typo: "ordatabase" → "or database".

Line 231 contains a word boundary issue where two words are concatenated.

🔎 Proposed fix

- and simply adding data to the schema file, or constructing an empty database
- from the schema file and then using a script ordatabase editor to import data.
+ and simply adding data to the schema file, or constructing an empty database
+ from the schema file and then using a script or database editor to import data.

Also applies to: 231-231

🤖 Prompt for AI Agents

In docs/source/quick_start.rst around line 231, the phrase "ordatabase" is a
typo where two words are concatenated; change "ordatabase" to "or database" so
the sentence reads "...using a script or database editor to import data." Ensure
the spacing is corrected and run a quick spell/grammar check for any similar
concatenations nearby.