torbenandClaude Opus 5.5
4ec22d376d
Files changed: - CHANGES.md - README.md - VERSION - instructions/kb-profiles.md - instructions/link-taxonomy.md - instructions/page-lifecycle.md - instructions/wiki-ingest/SKILL.md - instructions/wiki-lint/SKILL.md - kb/entities/COLLECTION.md - kb/entities/INDEX.md - kb/entities/organizations/E3DC GmbH.md - kb/entities/people/E3DC GmbH.md - kb/index.md - kb/log.md - tools/CONTRACT.md - tools/chemenu/commands/lint.py - tools/chemenu/kb_scan.py - tools/chemenu/lint_core.py - tools/chemenu/tests/test_lint.py - tools/chemenu/tests/test_new_page.py - tools/chemenu/tests/test_type_resolver.py - tools/chemenu/tests/test_types_cmd.py - types/entity.md - types/entity.organization.md - types/entity.person.md - types/entity.schema.yaml Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
132 lines
7.2 KiB
Markdown
132 lines
7.2 KiB
Markdown
---
|
|
profile: entities
|
|
outbound:
|
|
entities: [depends-on, required-by, runs-on, hosts, uses, produces, consumes, maintains, owns, owned-by, authored, involves, member-of, alternative-to, implements, part-of, composition, supersedes, derived-from, adapted-from, see-also]
|
|
concepts: [implements, exemplifies, rests-on, applies-when, operates-on, invokes, authored, alternative-to, see-also]
|
|
sources: [evidenced-by, defined-in, see-also]
|
|
comparisons: [compares-with, see-also]
|
|
gtd: [see-also]
|
|
required_by_stack: false
|
|
---
|
|
|
|
# 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) for the rules the stack enforces - linking mechanics,
|
|
provenance, citation, the confidence machinery - and
|
|
[kb/CONVENTIONS.md](../CONVENTIONS.md) for what this instance decided: language, naming forms,
|
|
tone, relationship labels, the confidence rubric. Neither is restated here.
|
|
|
|
<!-- wikitool:toc -->
|
|
## Contents
|
|
|
|
- [Types offered](#types-offered)
|
|
- [Per-area emphasis](#per-area-emphasis)
|
|
- [People live on their organization's page until they earn their own](#people-live-on-their-organizations-page-until-they-earn-their-own)
|
|
- [Authorised labels](#authorised-labels)
|
|
- [Outbound linking](#outbound-linking)
|
|
- [What does not belong here](#what-does-not-belong-here)
|
|
<!-- /wikitool:toc -->
|
|
|
|
## Types offered
|
|
|
|
`entity` (`tools/wikitool types describe entity`). The `entity_type:` field selects the area:
|
|
|
|
| Area | Holds |
|
|
|------|-------|
|
|
| `codebases/` | Codebases, 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, by full name or common handle |
|
|
| `organizations/` | Companies, public bodies, associations and their departments, by the name they use themselves |
|
|
|
|
These are areas, not collections: they inherit this contract and carry no `COLLECTION.md`.
|
|
|
|
## Per-area emphasis
|
|
|
|
- **Codebases** - purpose, status, language/stack, owner, repository, dependencies on other
|
|
codebases 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.
|
|
- **Organizations** - what kind of body it is, what it stands to this wiki as (client, supplier,
|
|
vendor), and the people in it - see below.
|
|
|
|
## People live on their organization's page until they earn their own
|
|
|
|
A person whose source material is a name, a role and a field of work does not get a page: that
|
|
page would restate its own title, which is worse than the mention it came from (`wiki-ingest`
|
|
step 7). They get a `###` section under the `## Personen` heading of their organization's page
|
|
instead - role, field of work, one to three lines. The organization page is then the grouping a
|
|
directory level cannot be, and it sits inside the size a page should have rather than a dozen
|
|
stubs below it.
|
|
|
|
A person **is promoted** to a page of their own once a source carries material for one. Their
|
|
section shrinks to one line with a `[[wikilink]]`, their page carries `member-of` to the
|
|
organization, and every edge and anchor link that meant them moves to the new page. The steps are
|
|
[instructions/page-lifecycle.md](../../instructions/page-lifecycle.md) § "Promote a section to its
|
|
own page"; `wikitool lint` reports an anchor link left pointing at the vanished section as
|
|
`broken_anchors`.
|
|
|
|
Until then, a person is reached through their organization: a project page's edge points at the
|
|
organization (`consults: Kunde X`), and the prose names the person as `[[Kunde X#Anna Müller]]`.
|
|
An organization that outgrows its page - by `Split Threshold`, roughly 120-150 lines - splits off
|
|
a department or site as an organization page of its own, linked `part-of` the parent.
|
|
|
|
## Authorised labels
|
|
|
|
The `outbound:` block above is what `wikitool lint` and `xref add` check: which labels a page in
|
|
this collection may use, per destination. The catalogue they are drawn from - and what each one
|
|
asserts - is [instructions/link-taxonomy.md](../../instructions/link-taxonomy.md), which binds
|
|
nothing on its own.
|
|
|
|
Operational labels dominate here because an entity's relationships are mostly to other concrete things. `implements` points *out* to a concept; the concept does not point back unless that direction is a statement of its own.
|
|
|
|
Three of these carry a caveat this area produces more often than the others. `authored` belongs
|
|
on a person page pointing at what they made, and it is the label a dead or departed creator
|
|
takes - `owns` claims someone answers for the thing *now*. `alternative-to` is self-dual and is
|
|
written **once per pair**, never from both ends: a set of interchangeable tools is where a
|
|
mirrored clique grows fastest. `derived-from` and `adapted-from` are here for the fork and the
|
|
re-implementation - one tool worked up out of another - which is a lineage claim the operational
|
|
labels cannot make.
|
|
|
|
`involves` and `owned-by` are the participation labels, and they run the other way from
|
|
`authored`/`owns`/`maintains`: written on the codebase or system, pointing at the person or
|
|
organization - `[Codebase] involves [Person]`. `involves` is the contributor who neither answers
|
|
for the thing nor keeps it running; take `maintains` or `owns` from the person's side when one of
|
|
those is true instead. `owned-by` is `owns` read from the thing's side - write whichever page a
|
|
reader would ask the question on, not both by reflex.
|
|
|
|
`member-of` runs from a person page to the organization they belong to, and only from a person
|
|
who has been promoted to a page (see above) - everyone else is a section on that organization's
|
|
page already. It is not `part-of`: a department is a component of its company, a person is not,
|
|
and `part-of` stays for the department or site split off an organization that outgrew its page.
|
|
|
|
Adding a label here is a deliberate contract change, not a way around a refusal.
|
|
|
|
## 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 Integration.md`, not `HA Integrations.md`.
|