addressing feedback

Author: NoahMaizels

docs/documentation/gsoc.md

@@ -20,7 +20,7 @@ However, there are several key differences:
 
 - Unlike PSS, **GSOC only needs to mine the target chunk once**—multiple messages reuse it, making it **faster, cheaper**, and **more efficient** for recurring updates.
 - Unlike PSS, **No encryption** is used by default, making it unsuitable for handling sensitive data.
-
+- Unlike PSS, **GSOC chunks are not meant to be retrieved directly**. The SOC used to initiate a GSOC connection is used to listen for incoming messages only, the chunk itself is not meant to be retrieved since the incoming messages are not actually used to update the SOC since double-signing an SOC is undefined behavior.  
 
 ## Requirements
 

docs/documentation/pinning.md

@@ -5,7 +5,9 @@ slug: /pinning
 sidebar_label: Pinning
 ---
 
-Pinning allows you to guarantee that your uploaded content will always be available by storing it **locally on your own Bee node**. However, pinning **guarantee availability across the Swarm network**. Therefore you must use pinning along with the **stewardship utilities** included in `bee-js` to monitor the availability of your pinned content and reupload it if needed.
+Pinning allows you to guarantee that content will always be available by storing it **locally on your own Bee node**. 
+
+However, pinning ***does not*** guarantee availability across the Swarm network. Therefore you must use pinning along with the **stewardship utilities** included in `bee-js` to monitor the availability of your pinned content and reupload it if needed.
 
 In this section, you'll learn how to:
 
@@ -15,8 +17,6 @@ In this section, you'll learn how to:
 - View all currently pinned references
 - Remove pins that are no longer required
 
-
-
 ## Pinning and Unpinning Content
 
 To pin a reference (so it remains stored on your node):
@@ -33,7 +33,6 @@ await bee.unpin(reference)
 console.log('Reference unpinned and no longer tracked.')
 ```
 
-
 ## Checking if a Reference is Retrievable
 
 Use `isReferenceRetrievable(reference)` to verify if the content for a given Swarm reference is currently accessible on the network:
@@ -73,16 +72,6 @@ const pinStatus = await bee.getPin(reference)
 console.log('Pin info:', pinStatus)
 ```
 
-## Deleting a Tag After Use
-
-Once you’re done tracking an upload, you can delete the tag to keep your node clean:
-
-```js
-await bee.deleteTag(tag.uid)
-console.log("Deleted tag:", tag.uid)
-```
-
-
 ## Example Script
 
 The following script automates the process of checking all locally pinned references, verifying their retrievability from the network, and reuploading any that are missing. This ensures that your pinned data remains available even if it has dropped out of the Swarm network.

docs/documentation/soc-and-feeds.md

@@ -9,7 +9,7 @@ sidebar_label: SOC and Feeds
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
-Swarm provides the ability to store content in content-addressed [chunks](https://docs.ethswarm.org/docs/concepts/DISC/#content-addressed-chunks-and-single-owner-chunks) (CAC) whose addresses are derived from the chunk data, or Single Owner Chunks (SOC) whose addresses are derived from the uploader's own public key and chosen identifier. With single owner chunks, a user can assign arbitrary data to an address and attest chunk integrity with their digital signature.
+Swarm provides the ability to store content in content-addressed [chunks](https://docs.ethswarm.org/docs/concepts/DISC/#content-addressed-chunks-and-single-owner-chunks) (CAC) whose addresses are derived from the chunk data, or Single Owner Chunks (SOC) whose addresses are derived from the uploader's address and chosen identifier. With single owner chunks, a user can assign arbitrary data to an address and attest chunk integrity with their digital signature.
 
 Feeds are a unique feature of Swarm which simulate the publishing of mutable content on Swarm's immutable storage. ***Feeds constitute the primary use case for SOCs.*** Developers can use Feeds to version revisions of a mutable resource by indexing sequential updates to a topic at predictably calculated addresses. Because Feeds are built on top of SOCs, their interfaces are somewhat similar and use common concepts.
 
@@ -31,7 +31,7 @@ SOCs are powerful and flexible low-level feature which provide the foundation up
 :::
 
 :::warning SOCs are immutable!
-You might be tempted to modify a SOC's content to "update" the chunk. Reuploading of an SOC is forbidden in Swarm as it might create uncertain behavior. A Bee node will reject the API call if it finds an already existing SOC for the given address. Either use a different `identifier`, or you might be looking for feeds if you need to perform multiple updates to the same content.
+You might be tempted to modify a SOC's content to "update" the chunk. Reuploading of an SOC is discouraged as its behavior is undefined. Either use a different `identifier`, or you might be looking for feeds if you need to perform multiple updates to the same content.
 :::
 
 ### Uploading SOCs

docs/documentation/tracking-uploads.md

@@ -5,7 +5,13 @@ slug: /tracking-uploads
 sidebar_label: Tracking Uploads
 ---
 
-You can track the progress of your uploads using "tags". Each tag tracks how many chunks were **split**, **stored**, **seen**, and **synced** by the network. By creating a tag before uploading and passing it to the upload function, you make the upload *trackable, allowing you to confirm whether your uploaded data has been fully synced.
+You can track the progress of deferred uploads using "tags". Each tag tracks how many chunks were **split**, **stored**, **seen**, and **synced** by the network. By creating a tag before uploading and passing it to the upload function, you make the upload *trackable, allowing you to confirm whether your uploaded data has been fully synced.
+
+:::info
+Tracking with tags is used ***only for [deferred uploads](/docs/upload-download/#deferred-uploads)***. That is because when content is uploaded in a deferred manner, the content's reference hash will be returned *immediately*, often before the content has been fully synced to the network. Therefore tags should be used in order to confirm when the content has been fully synced and is retrievable. 
+
+With direct uploads, the reference hash is not returned until after the content has already been uploaded and fully synced to the network, so there is no need to track it after uploading.
+:::
 
 ## How It Works
 
@@ -43,12 +49,19 @@ This links the upload to your tag so you can monitor its progress.
 
 ### 3. Track Tag Progress
 
-Use `bee.retrieveTag(tagUid)` to check how many chunks have been split and how many are synced. Poll repeatedly until `synced === split` to know when the upload has fully propagated.
+Use `bee.retrieveTag(tagUid)` to monitor upload progress. Chunks that have **already been synced in the past** are counted in `seen`, while newly synced ones are in `synced`. Poll repeatedly until:
+
+```text
+synced + seen === split
+```
+
+This indicates that all chunks have either just synced or were already present in the network.
 
 ```js
 const tag = await bee.retrieveTag(tagUid)
 console.log(` - Total split: ${tag.split}`)
 console.log(` - Synced: ${tag.synced}`)
+console.log(` - Seen: ${tag.seen}`)
 ```
 
 ## Example Script
@@ -70,7 +83,7 @@ async function waitForTagSync(tagUid, interval = 800) {
     console.log(` - Seen: ${tag.seen}`)
     console.log(` - Synced: ${tag.synced}`)
 
-    if (tag.split > 0 && tag.synced >= tag.split) {
+    if (tag.split > 0 && tag.synced + tag.seen >= tag.split) {
       console.log("Upload fully synced!")
       break
     }
@@ -102,7 +115,8 @@ async function uploadNodesJsonWithTag() {
 uploadNodesJsonWithTag()
 ```
 
-Example terminal output:
+
+### Example Terminal Output
 
 ```bash
 Created new tag with UID: 85
@@ -115,11 +129,12 @@ Progress (Tag 85):
 Progress (Tag 85):
  - Total split: 1078
  - Stored: 0
- - Seen: 0
- - Synced: 1078
+ - Seen: 532
+ - Synced: 546
 Upload fully synced!
 ```
 
+
 ## Deleting Tags
 
 You can delete tags you no longer need using their uid:
@@ -132,4 +147,5 @@ console.log("Deleted tag:", tag.uid)
 ## References
 
 - [Bee docs – Syncing / Tags](https://docs.ethswarm.org/docs/develop/access-the-swarm/syncing)  
-- [Bee API Reference – `/tags`](https://docs.ethswarm.org/api/#tag/Tag)
+- [Bee API Reference – `/tags`](https://docs.ethswarm.org/api/#tag/Tag)
+

docs/documentation/upload-download.md

@@ -324,5 +324,5 @@ await bee.uploadData(postageBatchId, 'data', { deferred: false })
 ```
 
 :::tip
-If you do use `deferred: true`, make sure to use a [tag](/docs/upload-download/#using-tags-to-monitor-upload-progress) to track upload progress and confirm the success or failure of the upload.
+If you do use `deferred: true`, make sure to use a [tag](/docs/tracking-uploads/) to track upload progress and confirm the success of the upload.
 :::