Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 2 additions & 23 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,21 +30,14 @@ Read only the guides relevant to the task:

For an application that uses Redux, also read [Redux architecture](AgentGuidelines/Guidelines/Architecture/Redux.md).

Keep the following observability contract in the consumer repository's root `AGENTS.md` so implementation agents treat runtime diagnostics as part of lifecycle work. Copy it unchanged and update it when the marker version changes in this template.

```md
<!-- BEGIN THATFACTORY RUNTIME OBSERVABILITY CONTRACT v1 -->
## Runtime Observability

Treat privacy-safe runtime observability as part of implementing or changing stateful, asynchronous, fallible, or lifecycle-oriented behavior. Identify the meaningful success, failure, cancellation, recovery, and state-transition boundaries before handoff, and emit concise AppLogger events owned by the artifact that implements them. Dependency declaration or target linkage alone does not satisfy this requirement.

Every ThatFactory package log starts with its canonical emoji and uses its own stable subsystem. Never log credentials, account or record identifiers, share URLs, captured content, images, or other user-generated values as public metadata. Keep pure values and utilities silent when they have no meaningful diagnostic event; record that deliberate decision in the implementation handoff instead of adding initializer or property-access noise. Follow [Logging](AgentGuidelines/Guidelines/Logging.md) for ownership, privacy, severity, message design, and tests.
<!-- END THATFACTORY RUNTIME OBSERVABILITY CONTRACT v1 -->
```

Keep the following marked external-dependency contract in the consumer repository's root `AGENTS.md` so implementation agents receive the rule directly before they make dependency choices. Copy it unchanged and update it when the marker version changes in this template.

```md
<!-- BEGIN THATFACTORY EXTERNAL DEPENDENCY CONTRACT v1 -->
## External Dependency Policy

Expand All @@ -58,11 +51,7 @@ Apple system frameworks and the Swift standard library are not third-party depen

Follow [Development workflow](AgentGuidelines/Guidelines/Development.md) for the detailed policy.
<!-- END THATFACTORY EXTERNAL DEPENDENCY CONTRACT v1 -->
```

Keep the following documentation-maintenance contract in the consumer repository's root `AGENTS.md` so implementation agents receive it directly rather than only through a linked guide. Copy it unchanged and update it when the marker version changes in this template.

```md
<!-- BEGIN THATFACTORY DOCUMENTATION MAINTENANCE CONTRACT v1 -->
## Documentation Maintenance

Expand All @@ -72,11 +61,7 @@ Update documentation when a change alters durable or core feature behavior or an

Do not create documentation churn for incidental implementation details that are not durable and do not affect an existing documented claim. Follow [Documentation](AgentGuidelines/Guidelines/Documentation.md) for detailed scope and the completion checklist.
<!-- END THATFACTORY DOCUMENTATION MAINTENANCE CONTRACT v1 -->
```

Keep the following marked code-review contract in the consumer repository's root `AGENTS.md` so it is loaded directly for root-level Codex and pull-request work. Copy it unchanged and update it when the marker version changes in this template; a Markdown link to the detailed workflow is not an instruction include.

```md
<!-- BEGIN THATFACTORY CODE REVIEW CONTRACT v2 -->
## Code Review Rules

Expand All @@ -98,16 +83,10 @@ Automatic Codex review is the initial Codex review. Do not request a manual Code
## Codex review scope

For consumer pull requests, do not substantively review `AgentGuidelines/**` after exact tagged-tree provenance has been verified. Verify its `VERSION`, compare its tree with the matching central tag, and verify the required `.gitattributes` rule. If provenance does not match exactly, review the subtree contents and stop the merge. Report substantive guideline feedback against the central `agent-guidelines` pull request.
```

The marked block is intentional controlled duplication of the shared review policy. The tracked, synchronized subtree is reviewed centrally in `thatfactory/agent-guidelines`; the root-level instructions ensure the review contract and subtree scope are loaded even when Codex starts from the repository root.

## Physical folder map

Replace these examples with exact repository paths:

| Role | Physical folder |
|---|---|
| --- | --- |
| Package sources | `Sources/LexiconKit/` |
| DocC catalog | `Sources/LexiconKit/LexiconKit.docc/` |
| Unit tests | `Tests/LexiconKitTests/` |
Expand All @@ -123,4 +102,4 @@ Replace these examples with exact repository paths:

- Do not encode CEFR, product progression, CloudKit, or application-specific deduplication policy.
- Store only opaque host-owned media references, never framework image objects or temporary URLs.
- LexiconKit currently emits no runtime diagnostics because its public surface contains only pure domain values and initializers. Do not log value construction or vocabulary content. If a stateful or fallible lifecycle is added, route its diagnostics through a package-local `LexiconLogging` gateway with subsystem `com.thatfactory.lexiconkit` and canonical emoji 📖.
- Model open success and failure are logged through `LexiconLogging` with subsystem `com.thatfactory.lexiconkit` and canonical emoji 📖. Never log model paths, lookup terms, glosses, or vocabulary content.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 7 additions & 0 deletions AgentGuidelines/CHANGELOG.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions AgentGuidelines/Guidelines/Packages.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions AgentGuidelines/README.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 12 additions & 0 deletions AgentGuidelines/Scripts/validate_guidelines.swift

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

38 changes: 38 additions & 0 deletions AgentGuidelines/Tests/run_tests.swift

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion AgentGuidelines/VERSION

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,17 @@ All notable changes to LexiconKit are documented here.

## Unreleased

## 0.3.0 — 2026-09-21

### Added

- Add a memory-mapped, language-neutral lexicon model reader with synchronous exact term and gloss lookup.
- Add explicit model verification for CI and installed-resource integrity checks.

### Changed

- Adopt Agent Guidelines `0.0.34`.

## 0.2.0 — 2026-09-20

### Added
Expand Down
20 changes: 17 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@

# LexiconKit

LexiconKit is a reusable, UI-agnostic domain package for personal vocabulary collections, definitions, provenance, lightweight metadata, and opaque references to host-owned media.
LexiconKit is a reusable, UI-agnostic domain package for personal vocabulary collections and immutable lexical model lookup.

LexiconKit provides persistence-friendly values for vocabulary entries, terms, optional grammatical gender, definitions, definition provenance, tags, and opaque host-owned media references. Dictionary lookup, translation, language-specific display articles, exercises, persistence frameworks, synchronization, and UI remain outside its boundary.
LexiconKit provides persistence-friendly vocabulary values plus a synchronous, language-neutral reader for versioned packed lexicon artifacts. Translation, fuzzy or semantic inference, language-specific display articles, exercises, persistence frameworks, synchronization, and UI remain outside its boundary.

```swift
let entry = LexiconEntry(
Expand All @@ -32,13 +32,27 @@ let entry = LexiconEntry(
)
```

Open a bundled model lazily and perform exact lemma or inflected-form lookup without deserializing the corpus:

```swift
let model = try LexiconModel(
contentsOf: modelURL,
manifestURL: manifestURL
)
let result = try model.matchSense(
for: "See",
gloss: "lake",
languageCodes: ["en"]
)
```

## Documentation

API documentation is published with DocC after a GitHub release. See the [LexiconKit documentation](https://thatfactory.github.io/lexiconkit/documentation/lexiconkit/).

## Runtime diagnostics

LexiconKit currently emits no runtime diagnostics. Its public surface contains only pure domain values and initializers; persistence, synchronization, validation workflows, and application lifecycle remain host responsibilities. Logging value construction would add noise and could expose vocabulary content. If the package later gains stateful or fallible runtime behavior, its diagnostics will use a package-local `LexiconLogging` gateway, subsystem `com.thatfactory.lexiconkit`, and the canonical 📖 prefix.
LexiconKit logs privacy-safe model-open success and failure through its package-local gateway, subsystem `com.thatfactory.lexiconkit`, and canonical 📖 prefix. It never logs model paths, lookup terms, glosses, or vocabulary content. Individual lookups remain silent.

## Requirements

Expand Down
Loading