update

website/content/_index.md

@@ -26,5 +26,15 @@ pit hello
 
 <div class="home-links">
   <a href="/start/">Get Started</a>
-  <a href="/docs/">Documentation</a>
+  <a href="/manual/">Language Manual</a>
+</div>
+
+<div class="donate-section">
+
+## Support ƿit
+
+ƿit is free and open source. If you find it useful, consider supporting its development.
+
+Donation options coming soon.
+
 </div>

website/content/cli/_index.md

@@ -0,0 +1,175 @@
+---
+title: "Command Line Interface"
+description: "The pit tool"
+type: "standalone"
+---
+
+ƿit provides a command-line interface for managing packages, running scripts, and building applications.
+
+## Basic Usage
+
+```bash
+pit <command> [arguments]
+```
+
+## Commands
+
+### pit version
+
+Display the ƿit version.
+
+```bash
+pit version
+# 0.1.0
+```
+
+### pit install
+
+Install a package to the shop.
+
+```bash
+pit install gitea.pockle.world/john/prosperon
+pit install /Users/john/local/mypackage  # local path
+```
+
+### pit update
+
+Update packages from remote sources.
+
+```bash
+pit update              # update all packages
+pit update <package>    # update specific package
+```
+
+### pit remove
+
+Remove a package from the shop.
+
+```bash
+pit remove gitea.pockle.world/john/oldpackage
+```
+
+### pit list
+
+List installed packages.
+
+```bash
+pit list              # list all installed packages
+pit list <package>    # list dependencies of a package
+```
+
+### pit ls
+
+List modules and actors in a package.
+
+```bash
+pit ls              # list files in current project
+pit ls <package>    # list files in specified package
+```
+
+### pit build
+
+Build the current package.
+
+```bash
+pit build
+```
+
+### pit test
+
+Run tests.
+
+```bash
+pit test            # run tests in current package
+pit test all        # run all tests
+pit test <package>  # run tests in specific package
+```
+
+### pit link
+
+Manage local package links for development.
+
+```bash
+pit link add <canonical> <local_path>  # link a package
+pit link list                          # show all links
+pit link delete <canonical>            # remove a link
+pit link clear                         # remove all links
+```
+
+### pit fetch
+
+Fetch package sources without extracting.
+
+```bash
+pit fetch <package>
+```
+
+### pit upgrade
+
+Upgrade the ƿit installation itself.
+
+```bash
+pit upgrade
+```
+
+### pit clean
+
+Clean build artifacts.
+
+```bash
+pit clean
+```
+
+### pit help
+
+Display help information.
+
+```bash
+pit help
+pit help <command>
+```
+
+## Running Scripts
+
+Any `.ce` file in the ƿit core can be run as a command:
+
+```bash
+pit version    # runs version.ce
+pit build      # runs build.ce
+pit test       # runs test.ce
+```
+
+## Package Locators
+
+Packages are identified by locators:
+
+- **Remote**: `gitea.pockle.world/user/repo`
+- **Local**: `/absolute/path/to/package`
+
+```bash
+pit install gitea.pockle.world/john/prosperon
+pit install /Users/john/work/mylib
+```
+
+## Configuration
+
+ƿit stores its data in `~/.pit/`:
+
+```
+~/.pit/
+├── packages/       # installed packages
+├── lib/            # compiled dynamic libraries
+├── build/          # build cache
+├── cache/          # downloaded archives
+├── lock.toml       # installed package versions
+└── link.toml       # local development links
+```
+
+## Environment
+
+ƿit reads the `HOME` environment variable to locate the shop directory.
+
+## Exit Codes
+
+- `0` — Success
+- Non-zero — Error (check output for details)

website/content/contributing/_index.md

@@ -0,0 +1,60 @@
+---
+title: "Contributing"
+description: "How to contribute to ƿit"
+type: "standalone"
+---
+
+ƿit is developed openly. Contributions of all kinds are welcome.
+
+## Report Bugs
+
+Found a problem? Open an issue on the [ƿit issue tracker](https://gitea.pockle.world/john/cell/issues). Include:
+
+- What you expected to happen
+- What actually happened
+- A minimal reproduction (a short `.ce` or `.cm` file)
+- Your platform and ƿit version (`pit version`)
+
+## Submit Packages
+
+Share your ƿit packages by hosting them on a Gitea instance. Any package with a valid `pit.toml` can be installed by others:
+
+```bash
+pit install gitea.example.com/you/your-package
+```
+
+See [Packages](/manual/#packages) for how to structure and publish packages.
+
+## Contribute to the Runtime
+
+The ƿit runtime is written in C. To build from source:
+
+```bash
+git clone https://gitea.pockle.world/john/cell
+cd cell
+make bootstrap
+```
+
+### Code Style
+
+- C code uses 2-space indentation
+- Functions and variables are `static` unless exported
+- No headers between files in the same package
+- Use `JS_NULL` / `JS_IsNull` — there is no `undefined`
+- Objects over classes; limit prototype usage
+
+### Submitting Patches
+
+1. Fork the repository on Gitea
+2. Create a branch for your change
+3. Keep commits focused — one logical change per commit
+4. Test your changes with `pit test all`
+5. Open a pull request with a clear description
+
+## Improve Documentation
+
+Documentation lives in the `docs/` directory as Markdown files. Fixes for typos, unclear explanations, or missing examples are always appreciated.
+
+## Code of Conduct
+
+Be respectful. Communicate clearly. Assume good faith. Technical disagreements are fine; personal attacks are not.

website/content/manual/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Language Manual"
+description: "Complete ƿit language reference"
+type: "manual"
+---

website/content/spec/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Language Specification"
+description: "ƿit internals for language implementers"
+type: "spec"
+---

website/content/start/_index.md

@@ -148,7 +148,6 @@ Your package can now use `pit build`, `pit test`, and install dependencies.
 
 ## What's Next
 
-- [**ƿit Language**](/docs/language/) — full syntax reference
-- [**Actors and Modules**](/docs/actors/) — the execution model in depth
-- [**Packages**](/docs/packages/) — code organization and sharing
-- [**Standard Library**](/docs/library/) — built-in modules
+- [**Language Manual**](/manual/) — full syntax reference, actors, packages, standard library
+- [**CLI Reference**](/cli/) — all `pit` commands
+- [**Language Spec**](/spec/) — internals for implementers

website/data/manual_sections.yaml

@@ -0,0 +1,58 @@
+sections:
+  - title: "Language Syntax"
+    page: "/docs/language/"
+    id: "language"
+  - title: "Actors and Modules"
+    page: "/docs/actors/"
+    id: "actors"
+  - title: "Requestors"
+    page: "/docs/requestors/"
+    id: "requestors"
+  - title: "Packages"
+    page: "/docs/packages/"
+    id: "packages"
+  - title: "Built-in Functions"
+    page: "/docs/functions/"
+    id: "functions"
+  - title: "Standard Library"
+    page: "/docs/library/"
+    id: "library"
+  - title: "text"
+    page: "/docs/library/text/"
+    id: "library-text"
+  - title: "number"
+    page: "/docs/library/number/"
+    id: "library-number"
+  - title: "array"
+    page: "/docs/library/array/"
+    id: "library-array"
+  - title: "object"
+    page: "/docs/library/object/"
+    id: "library-object"
+  - title: "blob"
+    page: "/docs/library/blob/"
+    id: "library-blob"
+  - title: "time"
+    page: "/docs/library/time/"
+    id: "library-time"
+  - title: "math"
+    page: "/docs/library/math/"
+    id: "library-math"
+  - title: "json"
+    page: "/docs/library/json/"
+    id: "library-json"
+  - title: "random"
+    page: "/docs/library/random/"
+    id: "library-random"
+  - title: "Writing C Modules"
+    page: "/docs/c-modules/"
+    id: "c-modules"
+  - title: "Kim Encoding"
+    page: "/docs/kim/"
+    id: "kim"
+  - title: "Nota Format"
+    page: "/docs/nota/"
+    id: "nota"
+  - title: "Wota Format"
+    page: "/docs/wota/"
+    id: "wota"

website/data/spec_sections.yaml

@@ -0,0 +1,25 @@
+sections:
+  - title: "DEC64 Numbers"
+    page: "/docs/spec/dec64/"
+    id: "dec64"
+  - title: "Value Representation"
+    page: "/docs/spec/values/"
+    id: "values"
+  - title: "Object Types"
+    page: "/docs/spec/objects/"
+    id: "objects"
+  - title: "Stone Memory"
+    page: "/docs/spec/stone/"
+    id: "stone"
+  - title: "Garbage Collection"
+    page: "/docs/spec/gc/"
+    id: "gc"
+  - title: "Bytecode VM"
+    page: "/docs/spec/bytecode/"
+    id: "bytecode"
+  - title: "Register VM"
+    page: "/docs/spec/mach/"
+    id: "mach"
+  - title: "Mcode IR"
+    page: "/docs/spec/mcode/"
+    id: "mcode"

website/hugo.toml

@@ -17,9 +17,21 @@ theme = 'knr'
     pageRef = '/start/'
     weight = 10
   [[menus.main]]
-    name = 'Documentation'
-    pageRef = '/docs/'
+    name = 'Manual'
+    pageRef = '/manual/'
     weight = 20
+  [[menus.main]]
+    name = 'Spec'
+    pageRef = '/spec/'
+    weight = 30
+  [[menus.main]]
+    name = 'CLI'
+    pageRef = '/cli/'
+    weight = 40
+  [[menus.main]]
+    name = 'Contributing'
+    pageRef = '/contributing/'
+    weight = 50
 
 [module]
   [[module.mounts]]

website/static/_redirects

@@ -0,0 +1,8 @@
+/docs/          /manual/              301
+/docs/language/ /manual/#language     301
+/docs/actors/   /manual/#actors       301
+/docs/packages/ /manual/#packages     301
+/docs/functions/ /manual/#functions   301
+/docs/library/  /manual/#library      301
+/docs/cli/      /cli/                 301
+/docs/c-modules/ /manual/#c-modules  301

website/themes/knr/layouts/manual/list.html

@@ -0,0 +1,19 @@
+{{ define "main" }}
+<div class="longform-layout">
+  <nav class="toc-nav" id="toc-nav">
+    <h3>Contents</h3>
+    <ul id="toc-list"></ul>
+  </nav>
+  <article class="longform-content" id="longform-content">
+    <h1>{{ .Title }}</h1>
+    {{ range .Site.Data.manual_sections.sections }}
+      <section id="{{ .id }}" data-toc-title="{{ .title }}">
+        {{ with $.Site.GetPage .page }}
+          {{ .Content }}
+        {{ end }}
+      </section>
+    {{ end }}
+  </article>
+</div>
+<script src="/js/toc.js"></script>
+{{ end }}

website/themes/knr/layouts/spec/list.html

@@ -0,0 +1,19 @@
+{{ define "main" }}
+<div class="longform-layout">
+  <nav class="toc-nav" id="toc-nav">
+    <h3>Contents</h3>
+    <ul id="toc-list"></ul>
+  </nav>
+  <article class="longform-content" id="longform-content">
+    <h1>{{ .Title }}</h1>
+    {{ range .Site.Data.spec_sections.sections }}
+      <section id="{{ .id }}" data-toc-title="{{ .title }}">
+        {{ with $.Site.GetPage .page }}
+          {{ .Content }}
+        {{ end }}
+      </section>
+    {{ end }}
+  </article>
+</div>
+<script src="/js/toc.js"></script>
+{{ end }}

website/themes/knr/layouts/standalone/list.html

@@ -0,0 +1,13 @@
+{{ define "main" }}
+<div class="longform-layout">
+  <nav class="toc-nav" id="toc-nav">
+    <h3>Contents</h3>
+    <ul id="toc-list"></ul>
+  </nav>
+  <article class="longform-content" id="longform-content">
+    <h1>{{ .Title }}</h1>
+    {{ .Content }}
+  </article>
+</div>
+<script src="/js/toc.js"></script>
+{{ end }}

website/themes/knr/static/css/main.css

@@ -49,7 +49,7 @@ body, h1, h2, h3, h4, p, ul, ol, figure, blockquote {
   --font-code: 'JetBrains Mono', 'Source Code Pro', 'Menlo', monospace;
   --font-wynn: 'Junicode', 'Charter', Georgia, serif;
   --content-width: 720px;
-  --sidebar-width: 220px;
+  --sidebar-width: 180px;
 }
 
 html {
@@ -444,3 +444,144 @@ th {
     margin-right: 0;
   }
 }
+
+/* ---- Longform Layout (Manual / Spec) ---- */
+.longform-layout {
+  max-width: calc(var(--content-width) + var(--sidebar-width) + 3rem);
+  margin: 0 auto;
+  display: flex;
+  gap: 2rem;
+  padding: 0 1.5rem;
+}
+
+.longform-content {
+  flex: 1;
+  min-width: 0;
+  padding: 2rem 0 3rem;
+}
+
+.longform-content h1 {
+  margin-bottom: 1.5rem;
+}
+
+.longform-content section {
+  margin-bottom: 3rem;
+}
+
+.toc-nav {
+  width: var(--sidebar-width);
+  flex-shrink: 0;
+  padding-top: 2rem;
+  position: sticky;
+  top: 0;
+  max-height: 100vh;
+  overflow-y: auto;
+}
+
+.toc-nav h3 {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-secondary);
+  margin-bottom: 0.5rem;
+}
+
+.toc-nav ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.toc-nav li.toc-section {
+  margin: 0;
+}
+
+.toc-nav li.toc-section > a {
+  display: inline;
+  font-size: 0.75rem;
+  color: var(--text-secondary);
+  line-height: 1.3;
+}
+
+.toc-nav li.toc-section > a:hover {
+  color: var(--text);
+  text-decoration: none;
+}
+
+.toc-nav li.toc-section > a.active {
+  color: var(--text);
+  font-weight: 700;
+}
+
+.toc-arrow {
+  display: inline-block;
+  width: 0.7em;
+  font-size: 0.65rem;
+  color: var(--text-secondary);
+  cursor: pointer;
+  transition: transform 0.15s;
+  user-select: none;
+}
+
+.toc-section.open > .toc-arrow {
+  transform: rotate(90deg);
+}
+
+.toc-sub {
+  display: none;
+  padding-left: 1rem;
+  margin: 0.1rem 0 0.2rem;
+}
+
+.toc-section.open > .toc-sub {
+  display: block;
+}
+
+.toc-sub li a {
+  display: block;
+  font-size: 0.7rem;
+  color: var(--text-secondary);
+  padding: 0.05rem 0;
+  line-height: 1.3;
+}
+
+.toc-sub li a:hover {
+  color: var(--text);
+  text-decoration: none;
+}
+
+/* ---- Donate Section ---- */
+.donate-section {
+  background: var(--bg-code);
+  border: 1px solid var(--border);
+  border-radius: 3px;
+  padding: 1.5rem 2rem;
+  text-align: center;
+  margin: 2rem 0;
+}
+
+.donate-section h2 {
+  border-bottom: none;
+  margin-top: 0;
+  padding-bottom: 0;
+}
+
+.donate-section p {
+  color: var(--text-secondary);
+  margin-bottom: 0.5rem;
+}
+
+@media (max-width: 768px) {
+  .longform-layout {
+    flex-direction: column;
+  }
+
+  .toc-nav {
+    width: 100%;
+    position: static;
+    max-height: none;
+    padding-top: 1rem;
+    border-bottom: 1px solid var(--border);
+    padding-bottom: 1rem;
+  }
+}

website/themes/knr/static/js/toc.js

@@ -0,0 +1,99 @@
+(function() {
+  var container = document.getElementById('longform-content');
+  var tocList = document.getElementById('toc-list');
+  if (!container || !tocList) return;
+
+  var sections = container.querySelectorAll('section[id]');
+  var allLinks = [];
+
+  if (sections.length > 0) {
+    // composite page (manual, spec): section-level ToC with disclosure
+    sections.forEach(function(sec) {
+      var li = document.createElement('li');
+      li.className = 'toc-section';
+      var a = document.createElement('a');
+      a.href = '#' + sec.id;
+      a.textContent = sec.dataset.tocTitle || sec.id;
+
+      var h2s = sec.querySelectorAll('h2');
+      if (h2s.length > 0) {
+        var toggle = document.createElement('span');
+        toggle.className = 'toc-arrow';
+        toggle.textContent = '\u25B8';
+        li.appendChild(toggle);
+        li.appendChild(a);
+
+        var sub = document.createElement('ul');
+        sub.className = 'toc-sub';
+        h2s.forEach(function(h) {
+          if (!h.id) return;
+          var sli = document.createElement('li');
+          var sa = document.createElement('a');
+          sa.href = '#' + h.id;
+          sa.textContent = h.textContent;
+          sli.appendChild(sa);
+          sub.appendChild(sli);
+        });
+        li.appendChild(sub);
+
+        toggle.addEventListener('click', function(e) {
+          e.preventDefault();
+          li.classList.toggle('open');
+        });
+      } else {
+        li.appendChild(a);
+      }
+
+      allLinks.push({el: sec, link: a, parent: li});
+      tocList.appendChild(li);
+    });
+
+    var currentSection = null;
+    var observer = new IntersectionObserver(function(entries) {
+      entries.forEach(function(entry) {
+        if (entry.isIntersecting) {
+          if (currentSection) currentSection.classList.remove('active');
+          var item = allLinks.find(function(i) { return i.el === entry.target; });
+          if (item) {
+            item.link.classList.add('active');
+            currentSection = item.link;
+            item.parent.classList.add('open');
+          }
+        }
+      });
+    }, {rootMargin: '0px 0px -70% 0px', threshold: 0});
+
+    sections.forEach(function(sec) { observer.observe(sec); });
+  } else {
+    // standalone page (cli, contributing): flat h2-only ToC
+    var headings = container.querySelectorAll('h2');
+    if (headings.length === 0) return;
+
+    headings.forEach(function(h) {
+      var li = document.createElement('li');
+      li.className = 'toc-section';
+      var a = document.createElement('a');
+      a.href = '#' + h.id;
+      a.textContent = h.textContent;
+      li.appendChild(a);
+      tocList.appendChild(li);
+      allLinks.push({el: h, link: a});
+    });
+
+    var current = null;
+    var obs = new IntersectionObserver(function(entries) {
+      entries.forEach(function(entry) {
+        if (entry.isIntersecting) {
+          if (current) current.classList.remove('active');
+          var item = allLinks.find(function(i) { return i.el === entry.target; });
+          if (item) {
+            item.link.classList.add('active');
+            current = item.link;
+          }
+        }
+      });
+    }, {rootMargin: '0px 0px -70% 0px', threshold: 0});
+
+    headings.forEach(function(h) { obs.observe(h); });
+  }
+})();