Interested-Deving-1896 documentation

This page is the documentation map for the Interested-Deving-1896 profile and its place in the OpenOS Project mirror chain. It brings the public-facing parts of the automation documentation together without duplicating project-specific secrets, quota tables, generated artifacts, or runbooks that must remain versioned with the automation source.

Profile and architecture

Complete automation reference

The canonical documentation index remains DOCS/SUMMARY.md. These direct links cover its main hand-written references:

Generated references—including the source tree, glossary, registered imports, subgroup map, workflow reference, origins, and eco audit—are linked from the canonical index so their URLs and generated counts stay synchronized with the control-plane repository.

Documentation publishing

The pages in this directory are the shared source for two independent outputs:

• GitBook reads .gitbook.yaml and DOCS/SUMMARY.md through Git Sync.
• GitHub Actions builds the same source with mdBook and deploys it through GitHub Pages.

Both outputs validate the organization-profile templates and generated target reference before building. GitHub Pages is published at https://interested-deving-1896.github.io/Interested-Deving-1896/ after Pages is configured to use GitHub Actions. GitBook connection is optional and does not affect the Pages build.

Repository roles

Creative documentation

Contribution direction

Open issues and pull requests against the relevant repository in the Interested-Deving-1896 source organization. OSP, OOC, and GitLab copies are continuity endpoints unless a repository explicitly states otherwise. Preserve upstream attribution and keep synchronization direction visible in all derived documentation.

Architecture

Interested-Deving-1896 maintains a personal profile, two independent organization identities, and a public documentation site from one repository. The organization READMEs are templates, not copies of the personal profile.

README.md                              personal profile

profiles/osp/README.md
  ├─► OpenOS-Project-OSP/OpenOS-Project-OSP:README.md
  └─► OpenOS-Project-OSP/.github:profile/README.md

profiles/ooc/README.md
  ├─► OpenOS-Project-Ecosystem-OOC/OpenOS-Project-Ecosystem-OOC:README.md
  └─► OpenOS-Project-Ecosystem-OOC/.github:profile/README.md

DOCS/
  ├─► GitBook through .gitbook.yaml
  └─► GitHub Pages through mdBook and GitHub Actions

Identity boundary

The publication manifest requires the appropriate organization identity in each template and rejects personal-profile names. Publishing only updates the four declared README files. It never mirrors the complete repository or copies the personal README into an organization.

Documentation boundary

GitBook and mdBook consume the same DOCS/ source and DOCS/SUMMARY.md navigation. Generated reference pages come from checked-in configuration and are validated before either documentation system builds.

Organization README publication

Organization README content is maintained in two canonical templates:

• profiles/osp/README.md
• profiles/ooc/README.md

The destination allowlist is stored in config/profile-targets.json. Changes to a template and repository-specific policy are validated. The template can then be published to its organization-named repository and special .github/profile/README.md destination; the policy is published only to the organization-named repository.

The same manifest separately allowlists portable repository automation. Those files are mirrored unchanged to the two organization-named README repositories and derive their active identity from github.repository_owner; organization profile repositories continue to receive only profile/README.md.

Workflows

Shared repository automation

The organization-named README repositories receive these portable workflows:

• guarded, collaborator-invoked AI assistance;
• read-only repository and workflow auditing;
• manual sanitized support-bundle generation;
• a local content server/client smoke test;
• a contributor-association trust gate for automation-sensitive changes; and
• path-based pull-request labeling;
• policy-driven README quality reports;
• rendered and accessible preview artifacts; and
• manual, pull-request-only maintenance proposals.

The workflow engines under scripts/ are mirrored unchanged. Each named README repository instead receives its own config/readme-policy.json, so OSP and OOC retain their own required identity, headings, badges, and managed content.

Each named README repository also receives an organization-specific fictional Stewardship Ledger under characters/lore/. The OSP and OOC variants are independently written and identity-validated; neither is copied into the other organization. Their operational profile READMEs contain only a factual link to the corresponding lore file.

Fork-Sync-All control-plane jobs that mutate other repositories, operate the FSA API, deliver diagnostics externally, or require the full cross-forge vouch registry are intentionally excluded.

Credential boundary

Cross-repository publication requires PROFILE_SYNC_TOKEN, preferably a fine-grained personal access token or GitHub App installation token with Contents read/write access to only these repositories:

• OpenOS-Project-OSP/OpenOS-Project-OSP
• OpenOS-Project-OSP/.github
• OpenOS-Project-Ecosystem-OOC/OpenOS-Project-Ecosystem-OOC
• OpenOS-Project-Ecosystem-OOC/.github

The broad Fork-Sync-All synchronization token is deliberately not used. Without PROFILE_SYNC_TOKEN, publication safely skips while validation and public drift checks remain available.

AI-assisted translation and drafting are opt-in. Configure the repository variable README_AI_ENDPOINT with an HTTPS OpenAI-compatible chat-completions endpoint and the secret README_AI_TOKEN; README_AI_MODEL may override the model declared in the local policy. Generated content is an artifact and, when requested, a pull request—never a direct update to the default branch.

Opening a proposal pull request uses README_MAINTENANCE_TOKEN when present. Use a narrowly scoped fine-grained token with Contents and Pull requests read/write access to that repository. Without it, the workflow uses the built-in token only when the repository permits Actions to create pull requests; otherwise it retains the proposal as a downloadable artifact. This keeps the broader repository-wide “create and approve pull requests” permission optional.

Local commands

python3 scripts/profile_readmes.py validate
python3 scripts/profile_readmes.py generate-docs --check
python3 scripts/readme_policy.py quality --report readme-report.json
python3 scripts/readme_policy.py staleness
PROFILE_SYNC_TOKEN=... python3 scripts/profile_readmes.py sync --check
PROFILE_SYNC_TOKEN=... python3 scripts/profile_readmes.py sync --dry-run

Organization README publication targets

This page is generated from config/profile-targets.json. The two organization templates are independent identities; the personal profile README is not copied into either organization.

Publication validates identity boundaries before making any update. Drift verification compares each remote file byte-for-byte with its canonical organization template.

Shared automation targets

The following portable files are mirrored unchanged to both organization README repositories. They derive repository identity at runtime.

Repository-specific README policies

Each named README repository receives its own policy; policies are not copied across organization boundaries.

Organization-specific fictional lore

Each named README repository receives a Stewardship Ledger variant written only for that repository's identity. Detailed fiction remains outside the operational organization profile README.

Organization-specific repository payloads

Documentation sites, community-health files, and preview assets are published only to their matching named README repository.

Publication authentication and repository settings

The organization-profile publisher is ready to use a narrowly scoped GitHub App. Until the App is installed, validated source changes remain safe: the publisher validates them and skips cross-repository writes when no credential is available.

Preferred GitHub App configuration

Create one private GitHub App and install it separately in OpenOS-Project-OSP and OpenOS-Project-Ecosystem-OOC. Limit each installation to that organization's named README repository and .github repository.

Grant these repository permissions:

• Contents: read and write
• Workflows: read and write
• Metadata: read

In Interested-Deving-1896/Interested-Deving-1896, configure:

• Actions variable PROFILE_SYNC_APP_ID with the App ID
• Actions secret PROFILE_SYNC_PRIVATE_KEY with a current App private key

The publication matrix requests a separate installation token for each destination organization. OSP credentials are never passed to the OOC job, and OOC credentials are never passed to the OSP job.

Fine-grained personal access tokens restricted to each organization's two destination repositories can be used temporarily as PROFILE_SYNC_OSP_TOKEN and PROFILE_SYNC_OOC_TOKEN. The broad legacy PROFILE_SYNC_TOKEN is retained only for migration and should be removed after the App is verified.

Run Publish organization READMEs manually with dry_run enabled after installing the App. A successful dry run should report every destination as current without creating a commit.

Social preview images

The prepared 1280×640 preview assets are:

• assets/social-preview.png
• profiles/osp/assets/social-preview.png
• profiles/ooc/assets/social-preview.png

GitHub does not provide a supported repository API for selecting a social preview image. An administrator must upload the matching PNG in each repository's Settings → General → Social preview panel. The SVG files beside the PNGs are the editable canonical artwork.

Owner decisions still required

A repository license must be selected explicitly before adding LICENSE. Likewise, CODEOWNERS should be added only after confirming assignable users or organization team slugs for all three repositories.

Forge-neutral README subsystem

The README subsystem separates reusable automation from profile identity and uses forge-neutral terms throughout its contract:

• a namespace may be a GitHub organization or user, a GitLab group or subgroup, a Gitea/Forgejo organization, or another forge's equivalent;
• a project is the hosted Git repository;
• a profile surface is whichever README location a forge chooses to expose.

The machine-readable contract is config/readme-subsystem.json, validated by schema/readme-subsystem.schema.json. The local engine is scripts/readme-subsystem.py, and readme-subsystem/action.yml provides the GitHub Actions adapter. The same Python commands run in GitLab CI or any other CI system with Python 3. Tested contract fixtures cover GitLab groups and subgroups, Gitea organizations, Forgejo/Codeberg namespaces, and generic Git workspaces.

Ownership and flow

This is intentionally not a bidirectional file mirror. Every artifact has one owner. Reusable improvements made while working in a profile repository are contributed back to Fork-Sync-All, then flow forward from the canonical owner. That promotion path prevents an update from bouncing indefinitely among four repositories.

The three profile repositories remain the reference skeleton: they demonstrate policy checks, preview artifacts, content smoke tests, repository audits, mdBook/GitBook sources, Pages deployment, accessibility, and organization- specific content. Fork-Sync-All owns only the reusable engines and coordination.

Template-managed profile chain

config/template-manifest.yml defines the narrow readme-profile profile. It contains reusable policy/link engines, subsystem provenance, and a generic consumer workflow. It intentionally excludes README.md, lore, funding, support tiers, profile payloads, and organization-specific documentation.

The delivery chain is single-writer at every hop:

1. Fork-Sync-All applies readme-profile patches to Interested-Deving-1896/Interested-Deving-1896.
2. The profile source's allowlisted publisher adapts and publishes shared automation plus organization-specific content.
3. OpenOS-Project-OSP/OpenOS-Project-OSP and OpenOS-Project-Ecosystem-OOC/OpenOS-Project-Ecosystem-OOC are registered as tier: delegated; Fork-Sync-All records them in the template chain but never writes them directly.

This makes template patches continuous without turning distinct profile repositories into raw Git mirrors or introducing competing automation writers.

Commands

python3 scripts/readme-subsystem.py validate
python3 scripts/readme-subsystem.py lock --check
python3 scripts/readme-subsystem.py plan
python3 scripts/readme-subsystem.py sync \
  --target interested-deving-1896 \
  --target-root /path/to/profile-checkout

Add --check to the sync command to report drift without writing. The engine only works on local checkouts; authentication, cloning, review branches, and push policy remain responsibilities of the CI adapter for each forge.

To suggest a reusable improvement discovered in the profile source, generate a review bundle instead of reverse-syncing files:

python3 scripts/readme-subsystem.py propose-upstream \
  --profile-root /path/to/profile-checkout \
  --output-dir /tmp/readme-subsystem-proposal

The bundle contains proposal.json with old and proposed checksums and a unified patch. Applying or opening that patch upstream is always a separate, human-reviewed action. Binary differences are reported for manual review.

Releases and provenance

readme-subsystem/VERSION is the subsystem release, and readme-subsystem/CHANGELOG.md records compatibility changes. Consumers should pin the immutable release tag or the reviewed major tag:

- uses: Interested-Deving-1896/fork-sync-all/readme-subsystem@readme-subsystem-v1

For maximum reproducibility, replace the major tag with an immutable commit SHA. config/readme-subsystem.lock.json binds the release tag, contract, and every canonical promoted artifact to SHA-256 checksums. Both GitHub and GitLab CI reject stale provenance.

Safe continuous cross-porting

The GitHub workflow validates the contract on every relevant change. On main and its weekly schedule it publishes canonical changes to a dedicated branch and opens or updates a pull request in the profile source. It never pushes directly to the protected default branch. After review, the profile source's existing publisher fans profile-owned content out to OSP and OOC. Other forges can call the same local sync command from their CI.

The preferred credential is a GitHub App installed only on the profile source with Contents: write and Pull requests: write repository permissions. Set README_SUBSYSTEM_APP_ID as a repository variable and README_SUBSYSTEM_APP_PRIVATE_KEY as a secret. SYNC_TOKEN remains a transition fallback and should be removed once the App is configured.

For non-GitHub hosts, use a project-scoped bot credential and open a merge or change request using that forge's adapter. The core contract deliberately uses namespace/project terms and does not require an organization concept.

Drift and operational status

scripts/readme-subsystem-status.py clones declared projects, checks canonical engine checksums, verifies the Interested-Deving-1896 → OSP → OOC content chain, and requests every configured Pages URL. The scheduled status workflow publishes JSON and Markdown artifacts and maintains one GitHub issue as the current dashboard. Drift is visible without allowing the monitor to modify any profile repository.

Live-chain admission

config/live-chain-manifest.json is the reviewed admission boundary for the source and mirror namespaces. A project being present in config/gitlab-subgroups.yml only assigns GitLab placement; it does not grant permission to create or update that project in the live GitHub mirror chain. scripts/mirror-orgs.sh intersects the placement registry with the admitted project list before its first API lookup and fails closed when the manifest is missing or invalid.

Every admitted project declares a README disposition:

• managed applies the shared README baseline and requires a canonical source plus both mirrors;
• exception requires a reason and documents why the common README baseline does not apply.

The scheduled mirror README audit reports any live project that is absent from the manifest as unapproved. To admit a project intentionally, add it to the manifest in the same reviewed change that adds its placement. Validate locally before merging:

python3 scripts/validate-live-chain-manifest.py

Digital sovereignty

The profile's digital-sovereignty direction follows practical engineering principles: people and organizations should be able to understand, host, adapt, replace, and migrate the technology they depend on.

For this repository, that means:

• keeping profile identities and publication targets explicit;
• publishing from inspectable templates rather than hidden transformations;
• using open Markdown sources shared by GitBook and mdBook;
• restricting automation credentials to the smallest required repository set;
• preserving portability between documentation hosts; and
• ensuring that no single downstream copy silently becomes the authority.

Read KDE's digital-sovereignty guidance and the project's creative provenance for the engineering and fictional contexts respectively.

Mirrorchain creative system

Mirrorchain supplies a friendly creative language for the source, operational, and ecosystem layers without replacing their factual documentation.

The organization templates contain only the expression appropriate to that organization: OSP uses the Continuity Prism and Mirror Keeper; OOC uses the Connection Constellation and Ecosystem Wayfinder.

Continue with the character index, Mirrorchain folklore, Stewardship Ledger tier folklore, and creative provenance.