Platform documentation
Forgeworks Guide
Purpose, principles, design, architecture, licensing, and maintenance.
1. Purpose
Forgeworks is one home for intellectual work, creative work, and useful tools. It provides shared structure without pretending that an essay, a Minecraft build, a browser utility, and a private archive are the same kind of object.
This Guide makes the platform self-describing. A visitor, future maintainer, or AI system should be able to learn how Forgeworks is meant to work from Forgeworks itself. The public Guide and the repository documents describe the same system at different levels of technical detail.
2. Scope and principles
Forgeworks shares a platform, visual system, and a small set of public commitments. It does not make every project follow one epistemic or documentation template. Requirements follow the kind of work, its complexity, and the claims it actually makes.
For claim-bearing work. Build maps that reality can correct.
Where a work makes factual, analytical, or philosophical claims, it should expose the evidence, assumptions, scope, uncertainty, and conditions that could change it. Confidence belongs to individual claims rather than transferring automatically from the surrounding document or project.
Platform-wide commitments
- Identifiable
- Each work states what it is, who made it, its present status, and where it belongs.
- Rights stated
- An operative licence or the absence of one is explicit, including relevant third-party boundaries.
- Inspectable
- Purpose, material limits, dependencies, and provenance are supplied where they affect understanding or use.
- Portable where applicable
- Source, documents, worlds, and exports remain usable outside one host when a portable form exists and can lawfully be supplied.
- Non-extractive
- Forgeworks and its first-party tools do not make access conditional on surveillance, manipulation, or lock-in.
Requirements follow the work
| Kind | What travels with it | What is not imposed |
|---|---|---|
| Intellectual | Claim type, sources, scope, assumptions, uncertainty, standing, and correction conditions where they bear on the conclusion. | A fixed apparatus on every text. Short practical or reflective pieces may remain short. |
| Creative | Creator, title, date or version, medium, credits, third-party material, licence, and any instructions needed to use the work. | Evidence ledgers, falsification conditions, or a theory of the artwork merely for formal symmetry. |
| Software | Purpose, supported environment, inputs and outputs, data behaviour, status, limitations, source and build guidance, test standing, and licence where relevant. | Intellectual-document grammar or explanations that do not help operation, inspection, maintenance, or reconstruction. |
Self-description is proportional rather than maximal. A Minecraft build pack may need a short readme with version, compatibility, installation, credits, and licence; it does not need a document explaining how it could be disproved. A complex app may need architecture, data boundaries, tests, and reconstruction instructions. The object carries the explanation that helps someone understand, use, preserve, or continue it—no more by default.
3. Design system
Every visible element must carry information, establish hierarchy, enable action, or improve comprehension. Ornament without a job is removed. Restraint is not an aesthetic pose; it protects signal.
Shared visual rules
- BatchForge is the visual reference for repeated interface elements; Forgeworks documents and versions the governing contract.
- Every family site loads the same executable interface stylesheet rather than separately approximating shared elements.
- All three themes preserve the same hierarchy; Dark Gray is the first-visit default, and one choice follows the visitor across the `myforgeworks.net` family.
- Platform and project Guides use the shared sans-serif documentation grammar. Serif is reserved for long-form intellectual work.
- Project accents identify domains through the labelled kind; project-card surfaces and borders remain neutral.
- Each project name and its kind share one top row, with the kind aligned right. The compact row removes empty vertical space without weakening hierarchy.
- Semantic control colours and labelled project identity colours are separate systems. LostMediaForge may use a Minecraft-associated green while success states remain explicitly labelled.
- Cards communicate that they are surfaces. Otherwise-inert text actions receive a visible hairline or equivalent affordance.
- Footers contain one Guide link; they do not repeat identity, purpose, or individual documentation sections already available behind it.
- Spacing, borders, corners, controls, and typography come from shared tokens rather than page-specific approximations.
- Motion is functional and restrained. Repeated interface chrome has no ambient animation.
- No icon font, emoji chrome, non-semantic ambient animation, engagement badge, or decorative dashboard statistic.
Convergence does not mean uniformity. Editorial pages retain generous reading space; tools retain denser working surfaces. Shared primitives make them recognizably related while each project keeps the layout its function requires.
| Repeated element | Fixed contract |
|---|---|
| Header | Full-width translucent bar; 72px inner row; 18px blur; shared content alignment. |
| Brand | Same wordmark type, spacing, and alignment. Exocortex alone may place its approved mark at 1em before its wordmark without changing header height. |
| Theme control | Three labelled 27px controls: a sun for Light, a moon for Dark Gray, and a black dot for Pure Black. Dark Gray is the first-visit default. |
| Primary introduction | 62px top offset, reduced to 40px below 820px and 32px below 520px; 42–72px bold title; 17px description at a 620px measure; 14px description below 520px. |
| Cards and actions | 18px card corners; 46px primary actions with 10px corners and project accent. |
| Footer | One Guide link in the shared utility row; same width, 12px type, spacing, and border; right-aligned on desktop and left-aligned on mobile. |
| Guide index | The same restrained contents column on every family Guide, collapsing above the document on smaller screens. |
| Guide body | Left-aligned IBM Plex Sans documentation with the same heading scale, section rules, tables, links, and reading width across family sites. |
| Accent glow | Same radial geometry, coloured by project identity: amber for Forgeworks and Exocortex, green for BatchForge, and red for FetchKiln. |
Wording
Interface copy names the section or action, states the necessary fact, and stops. It avoids promotional filler, nearby repetition, and changing project counts or versions in overview prose when structured records already carry that information. An action that only scrolls to content immediately below it is omitted.
4. Document grammar
Epistemic Forge established a useful long-form intellectual grammar. Forgeworks preserves the grammar while replacing hard-coded, light-only styling with reusable, theme-aware components. This is distinct from the simpler sans-serif grammar used by project and platform Guides.
| Element | Purpose |
|---|---|
| Title and subtitle | Name the claim and its exact scope. |
| Document type | Distinguish an audit, argument, synthesis, guide, release, or creative work. |
| Author, collaborators, version | Make responsibility, provenance, and revision state visible. |
| Abstract | State the complete argument compactly before detail. |
| Epistemic key | Prevent textual fact, empirical finding, inference, legal status, and judgment from laundering one another. |
| Indexed sections | Keep long arguments navigable and referable. |
| Confidence ledger | Attach confidence and limitations to specific claims. |
| Assumptions and kill conditions | Expose what bears the conclusion and what would defeat it. |
| References and lineage | Preserve external evidence and the work’s place inside the corpus. |
| Licence and AI disclosure | State reuse rights, collaboration, and retained responsibility. |
Not every document needs every element. The structure is selected by epistemic need, not filled mechanically. A short practical release should remain short.
5. Architecture
Forgeworks is a platform rather than a sequence of rebuilt pages. Project records, navigation, status, licences, and accents live as structured data. Pages render those records through shared components. Adding a project should normally mean adding one manifest entry and its content—not rebuilding the site shell.
| Layer | Responsibility |
|---|---|
| Design tokens | Theme colours, typography, spacing, corners, borders, motion, and semantic states. |
| Shared components | Header, theme switch, project cards, collection pages, article structure, tables, callouts, status and licence blocks. |
| Project manifests | Name, domain, description, status, licence, accent, link destination, version, and visibility. |
| Content | Intellectual, creative, tool, archive, and Guide material kept separate from layout code. |
| Contracts | Build, accessibility, link, schema, and theme checks that prevent quiet drift. |
| Decision record | Dated reasons for changes that future people and AI systems must not accidentally reverse. |
Maintenance firewall
Future AI work must extend the existing primitives, read the governing documents, preserve unrelated decisions, update the change record, and validate the result. Replacing the architecture with a fresh generated template is a defect.
6. Licensing
“Free” is not left as an implication. Every published item carries an explicit licence. Different objects require different licences, and one project’s licence does not silently transfer to another.
| Work | Default | Boundary |
|---|---|---|
| Essays and public prose | CC BY 4.0 | Reuse and adaptation with attribution. |
| Forgeworks site code and small tools | MIT | Use, copy, modify, and distribute with the notice retained. |
| Original creative works | CC BY 4.0 | The licence covers the author’s original contribution; Minecraft, Mojang, and other third-party material retain their own rights. |
| Exocortex | No operative licence yet | AGPLv3 for code and CC BY-SA 4.0 for documentation remain proposals, not grants. |
| Names and logos | Separate brand policy | Code and content licences do not automatically grant identity or endorsement rights. |
No paywall, premium tier, or donation may unlock rights or functionality withheld from other users. Optional support, where present, is a gift rather than a transaction for access.
7. AI collaboration
AI systems may assist with research, adversarial review, drafting, design, programming, migration, and testing. Their output is not accepted merely because it is fluent. Claims and implementations remain subject to evidence, comparison, and verification.
Relevant collaboration is disclosed. Contributions are judged by their content rather than their origin; authorship and final responsibility remain with the releasing human. The repository includes instructions designed to let future AI systems continue the project without reconstructing its architecture from conversation fragments.
8. Privacy and hosting
The Forgeworks website requires no account and contains no advertising, behavioural analytics, tracking pixel, or engagement machinery. A first-party preference cookie shares only the chosen theme—Light, Dark Gray, or Pure Black—across `myforgeworks.net` and its project subdomains. Local storage supplies immediate display and fallback behavior. The value is not an account or visitor identifier. External project links are labeled by context.
Hosting is replaceable. The source and content remain portable, and the custom domain remains an address rather than the architecture. Individual tools may make stronger privacy claims only when those claims are structurally true—for example, BatchForge’s in-browser conversion and Exocortex’s absence of Android internet permission.
9. Accessibility
- Semantic landmarks, heading order, labels, and keyboard operation are required.
- Body text begins at a readable size and remains usable at 200% enlargement.
- Colour never carries meaning alone; contrast is checked in all three themes.
- Long tables scroll within their own boundary instead of breaking the page.
- Motion respects reduced-motion settings, and touch targets remain usable on small screens.
- Long-form text is justified only where the measure supports it; mobile reading remains left-aligned.
10. Standing and correction
This is version 0.13 of the foundation, not a claim that the system is finished. The repeated interface is an executable contract shared exactly by Forgeworks, BatchForge, Exocortex, and FetchKiln rather than a set of visual suggestions. Their headers use the same wordmark geometry, static theme-control component, and primary introduction spacing and type. Dark Gray is the first-visit theme, and a first-party preference follows the visitor across the custom-domain family. Exocortex alone pairs its approved 1em mark with its wordmark. Project migrations and the complete creative archive remain open work. Shared requirements are now explicitly proportional to each work’s kind, complexity, and claims rather than imposed uniformly across unlike projects. Project cards pair the project name with its right-aligned semantic kind, and external actions name their actual destinations. Exocortex and FetchKiln now have project-specific download and documentation sites. Every family footer exposes one Guide doorway; each Guide starts with the same contents index and sans-serif documentation grammar, then contains the project-appropriate source, licence, architecture, and operating information behind it. The Forgeworks introduction uses the Guide as its sole action and keeps the project index subordinate to the projects it organizes.
Corrections should change both the public Guide and the corresponding repository rule. A decision that exists only in a chat is not yet part of the durable platform.