added project docs

astro.config.mjs

@@ -84,7 +84,6 @@ export default defineConfig({
           label: "Reference",
           autogenerate: { directory: "reference" },
         },
-
         {
           label: "Standard Library",
           items: [
@@ -99,6 +98,12 @@ export default defineConfig({
             { label: "OpenAI", link: "std/openai" },
           ],
         },
+        {
+          label: "Collaboration",
+          items: [
+            { label: "Forks and Branches", link: "collaboration/forks-branches" },
+          ],
+        },
         {
           label: "REST API",
           autogenerate: { directory: "api" },

src/content/docs/collaboration/branches.mdx

@@ -0,0 +1,67 @@
+---
+title: Branches
+description: Other users can fork your Project, and you can fork other user’s Projects.
+lastUpdated: 2025-01-30
+---
+
+Vals are immutable, but you can publish new versions of vals. Versions start at
+`0` and go up from there. When you reference a val, you always get the most
+recent version. You can toggle which version you're looking at via the dropdown
+menu next to the val's name.
+
+## Imports & pinning
+
+Vals are imported via esm.town URLs. If you leave off the version number, it's an unpinned import, and you'll always get the latest version. If you include a version number, it's a pinned import, and you'll always get that version.
+
+```ts title="Unpinned val import"
+import { myVal } from "https://esm.town/v/username/valname";
+```
+
+```ts title="Pinned val import"
+import { myVal } from "https://esm.town/v/username/valname?v=7";
+```
+
+When you import one of your own vals, via the `@` helper, it will be imported unpinned, so you will
+automatically get all new changes. When you import another user's val via `@`,
+it will pin your import to the most recent version of that val
+(ie it will end it `?v=7` or whatever the current version number is),
+so if they change it, you won't get automatic updates.
+
+This makes your code more stable and protects you against
+code injection attacks. You can override this default behavior if you trust the
+user not to break your code: remove the `v` query param in the import statement,
+and your code will always use the latest version of that val.
+
+### Versions of external imports
+
+You can also specify versions of NPM modules by using an `@` symbol:
+
+```ts
+import { min } from "npm:[email protected]";
+
+// Or you can specify a version range, like
+// you would in a package.json file:
+import { min } from "npm:lodash-es@4";
+```
+
+We highly recommend pinning imported modules because their APIs can
+change between versions and unexpectedly break your code.
+
+### Lockfiles
+
+When you save a Val we generate a
+[deno.lock](https://docs.deno.com/runtime/manual/basics/modules/integrity_checking/)
+lockfile. This pins all versions of your dependencies and also calculates hashes
+to verify that the content of a dependency does not change.
+
+When you save a Val, we regenerate the lockfile from scratch, re-pinning your
+unpinned dependencies to whatever their current versions are at that new time.
+
+Additionally, when you save a val, we find all the vals in your account that
+depend on that val and mark their lockfiles for regeneration. That way you can
+keep rapidly iterating and we'll make sure to update dependency relationships in
+your vals.
+
+Read more about how and why we use lockfiles here: https://blog.val.town/blog/lockfiles/
+
+You can also use a [lockfile import map](https://www.val.town/v/maxm/lockfileImportMap) if you need to make sure your val frontend and backend are always in sync.

src/content/docs/collaboration/forks-branches.mdx

@@ -0,0 +1,35 @@
+---
+title: Forks and Branches
+description: Other users can fork your Project, and you can fork other user’s Projects.
+lastUpdated: 2025-01-30
+---
+Forks and branches are important when collaborating with other users, or managing large scale projects. 
+
+### Forks vs. Branches
+
+- **Forks:** Forked vals and projects are linked to the original. They are often used for large-scale changes or cross-account collaboration. Changes in a fork can be merged back via pull requests. 
+- **Branches:** Introduced for projects, branches are ideal for feature development and iterative changes. They share project history and are typically merged back into the main branch when complete.
+
+### Forking
+Forking creates a copy of a val or project in your account while maintaining references to the original. For projects, forking includes the main branch when a non-main branch is forked to maintain consistency.
+
+### Branching
+
+- **Branch Merging:**  A branch can only be merged into its parent if there are no conflicts. All edits are copied to the parent project, and the fork version is updated to match the latest version in the parent.
+
+- **Pulling from Upstream:** Pull updates from the parent project into your fork as a single edit. The fork version updates to reflect the latest upstream changes.
+
+
+### Behavior and Limitations
+
+- **Merge Conflicts:** Merges cannot proceed with conflicts.
+
+- **Duplicate Forks, Project Names:** You cannot fork the same project again, or fork a project with the same name as an existing one. You also cannot fork your own projects at this time.
+
+
+### Differences from Git
+
+- **Merge Commits:** Operates like a squash merge, copying all edits instead of linking to history.
+
+- **Branch Parent:** Parent relationships are fixed; merged forks remain independent.
+

src/content/docs/index.mdx

@@ -42,11 +42,25 @@ There are **4 types of vals**, each with different _triggers_:
   />
 </CardGrid>
 
+##### Projects [Beta] overview
+Vals, while powerful, are limited as single-files. Managing large or interconnected codebases becomes difficult. Projects solve this by allowing you to organize and version multiple related files together.
+- **Versioned Workspace:** Projects track changes to vals, files, folders, READMEs with incremental versioning
+- **Multiple Entrypoints:** Define multiple HTTP, Cron, and Email vals, each with unique URLs, schedules, and configurations
+- **Collaboration Tools:** Fork projects, create branches, sync with upstream
+- **Relative Imports:** Import files and folders relative to the Project root without needing to adjust paths when branching or forking
+- **Static Files:** Add static files (HTML, CSS, text) to projects
+- **Scoped Environment Variables:** Project-scoped variables for secure configuration
+- **Streamlined Coding:** AI code completion and full-screen IDE with file tree, logs and browser preview
+
+:::note
+Don't see something you expected? Let us know by sending us an email at <a href="mailto:[email protected]">[email protected]</a>.
+:::
+
 ##### Where to start
 
 If you're new to Val Town, we recommend starting with [Townie](https://www.val.town/townie), our AI assistant that can write vals for you.
 
-We also reccomend our quickstarts.
+We also recommend our quickstarts.
 
 <CardGrid>
   <LinkCard

src/content/docs/reference/import.mdx

@@ -25,6 +25,8 @@ you type the `@` symbol.
 import { example1 } from "https://esm.town/v/stevekrouse/example1";
 ```
 
+You can also import files and folders relative to the project root (ie. `./home`), which means you don't have to update your imports when you branch, fork, or rename a project.
+
 All vals are hosted on [esm.town](/api/esm-town),
 and are available for import on Val Town, Deno, Node, the browser, and anywhere else https-imports are supported.
 In this way, Val Town builds upon the new http-style imports, to make a lightweight package registry,

src/content/docs/reference/version-control.mdx

@@ -2,7 +2,7 @@
 title: Version Control
 description: Every time you save a val it creates a new immutable version in the
   version history.
-lastUpdated: 2024-05-09
+lastUpdated: 2025-01-30
 ---
 
 Vals are immutable, but you can publish new versions of vals. Versions start at
@@ -63,4 +63,6 @@ depend on that val and mark their lockfiles for regeneration. That way you can
 keep rapidly iterating and we'll make sure to update dependency relationships in
 your vals.
 
-Read more about how and why we use lockfiles here: https://blog.val.town/blog/lockfiles/
+Read more about how and why we use lockfiles here: https://blog.val.town/blog/lockfiles/
+
+You can also use a [lockfile import map](https://www.val.town/v/maxm/lockfileImportMap) if you need to make sure your val frontend and backend are always in sync.