torben
18ae28f918
Chemenu kompiliert Rohnotizen zu einem verlinkten, quellengebundenen Wiki: raw/ -> types/ + tools/ -> kb/ -> reports/. Was mechanisch ist, macht tools/wikitool; was Urteil braucht, macht ein Agent unter Contracts, deren Grenzen in Code durchgesetzt sind statt im Prompt. Dieser Commit ist der Startpunkt der oeffentlichen Historie. Die vorherige Entwicklung fand in einer privaten Instanz statt und ist nicht Teil dieses Repositorys; ihre Erzaehlung steht vollstaendig in CHANGES.md, das mit 44 Eintraegen von 0.1.0 bis 2.1.0 erhalten geblieben ist. Der mitgelieferte Korpus ist ein Testbett und eine Demo: 170 Seiten ueber den Stack selbst - Gates, Lint, Versionierung, Suche, das Wiki-Muster. Er dokumentiert das Werkzeug mit den eigenen Mitteln des Werkzeugs. Lizenz: AGPL-3.0 fuer den Stack (tools/, types/), CC-BY-4.0 fuer die Inhalte. Die Grenze zwischen beiden ist der Dateiplan, den dist export berechnet - siehe NOTICE.
53 lines
2.4 KiB
Markdown
53 lines
2.4 KiB
Markdown
# kb/entities/ - Collection Contract
|
|
|
|
Concrete things that exist: a project, a deployed system, a CLI tool, a technology, a person or
|
|
an organization. If it can be pointed at, it is an entity.
|
|
|
|
**Quality goal:** pointability + currency - a reader should come away knowing what the thing
|
|
is, where it actually is, and whether that is still true. An entity page that describes a
|
|
system correctly but names no host, path, version or status has not earned its keep.
|
|
|
|
Inherits [kb/CONTRACT.md](../CONTRACT.md) - naming, tone, linking, provenance and confidence
|
|
are defined there and are not restated here.
|
|
|
|
## Types offered
|
|
|
|
`entity` (`tools/wikitool types describe entity`). The `entity_type:` field selects the area:
|
|
|
|
| Area | Holds |
|
|
|------|-------|
|
|
| `projects/` | Codebases and initiatives, named after their repository or common name |
|
|
| `systems/` | Deployed and running systems, given a descriptive name |
|
|
| `tools/` | CLI and desktop tools, named as the tool names itself |
|
|
| `technologies/` | Protocols, languages, formats, in their standard spelling and capitalization |
|
|
| `people/` | People and organizations, by full name or common handle |
|
|
|
|
These are areas, not collections: they inherit this contract and carry no `COLLECTION.md`.
|
|
|
|
## Per-area emphasis
|
|
|
|
- **Projects** - purpose, status, language/stack, owner, repository, dependencies on other
|
|
projects and systems, architectural decisions.
|
|
- **Systems** - purpose, components, dependencies, configuration locations, deployment,
|
|
operational status, monitoring.
|
|
- **Technologies** - purpose, use cases, trade-offs, version compatibility, which projects and
|
|
systems use it.
|
|
- **Tools** - purpose, installation, usage, notable options, which projects use it.
|
|
- **People** - role, affiliation, and the projects or decisions they are connected to. Nothing
|
|
personal beyond what the source states.
|
|
|
|
## Outbound linking
|
|
|
|
An entity links to the technologies it uses, the systems it runs on, the projects that depend
|
|
on it, and the concepts it implements.
|
|
|
|
An entity that mentions a concept without linking it is incomplete; the concept page is where
|
|
the *why* lives, and the entity page should not restate it.
|
|
|
|
## What does not belong here
|
|
|
|
- A pattern, protocol, architecture or decision - those are concepts, even when only one entity
|
|
uses them.
|
|
- A page about a source document - that is a `source` page in `kb/sources/`.
|
|
- Singular naming is required: `ha-core.md`, not `ha-cores.md`.
|